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 <stdint.h>
22 : #include <sys/types.h>
23 :
24 : #include <zephyr/sys/atomic.h>
25 : #include <zephyr/bluetooth/buf.h>
26 : #include <zephyr/bluetooth/conn.h>
27 : #include <zephyr/bluetooth/hci.h>
28 :
29 : #ifdef __cplusplus
30 : extern "C" {
31 : #endif
32 :
33 : /** L2CAP PDU header size, used for buffer size calculations */
34 1 : #define BT_L2CAP_HDR_SIZE 4
35 :
36 : /** Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU. */
37 1 : #define BT_L2CAP_TX_MTU (CONFIG_BT_L2CAP_TX_MTU)
38 :
39 : /** Maximum Transmission Unit (MTU) for an incoming L2CAP PDU. */
40 1 : #define BT_L2CAP_RX_MTU (CONFIG_BT_BUF_ACL_RX_SIZE - BT_L2CAP_HDR_SIZE)
41 :
42 : /** @brief Helper to calculate needed buffer size for L2CAP PDUs.
43 : * Useful for creating buffer pools.
44 : *
45 : * @param mtu Needed L2CAP PDU MTU.
46 : *
47 : * @return Needed buffer size to match the requested L2CAP PDU MTU.
48 : */
49 1 : #define BT_L2CAP_BUF_SIZE(mtu) BT_BUF_ACL_SIZE(BT_L2CAP_HDR_SIZE + (mtu))
50 :
51 : /** L2CAP SDU header size, used for buffer size calculations */
52 1 : #define BT_L2CAP_SDU_HDR_SIZE 2
53 :
54 : /** @brief Maximum Transmission Unit for an unsegmented outgoing L2CAP SDU.
55 : *
56 : * The Maximum Transmission Unit for an outgoing L2CAP SDU when sent without
57 : * segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.
58 : *
59 : * The MTU for outgoing L2CAP SDUs with segmentation is defined by the
60 : * size of the application buffer pool.
61 : */
62 1 : #define BT_L2CAP_SDU_TX_MTU (BT_L2CAP_TX_MTU - BT_L2CAP_SDU_HDR_SIZE)
63 :
64 : /** @brief Maximum Transmission Unit for an unsegmented incoming L2CAP SDU.
65 : *
66 : * The Maximum Transmission Unit for an incoming L2CAP SDU when sent without
67 : * segmentation, i.e. a single L2CAP SDU will fit inside a single L2CAP PDU.
68 : *
69 : * The MTU for incoming L2CAP SDUs with segmentation is defined by the
70 : * size of the application buffer pool. The application will have to define
71 : * an alloc_buf callback for the channel in order to support receiving
72 : * segmented L2CAP SDUs.
73 : */
74 1 : #define BT_L2CAP_SDU_RX_MTU (BT_L2CAP_RX_MTU - BT_L2CAP_SDU_HDR_SIZE)
75 :
76 : /**
77 : *
78 : * @brief Helper to calculate needed buffer size for L2CAP SDUs.
79 : * Useful for creating buffer pools.
80 : *
81 : * @param mtu Required BT_L2CAP_*_SDU.
82 : *
83 : * @return Needed buffer size to match the requested L2CAP SDU MTU.
84 : */
85 1 : #define BT_L2CAP_SDU_BUF_SIZE(mtu) BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu))
86 :
87 : /** @brief L2CAP ECRED minimum MTU
88 : *
89 : * The minimum MTU for an L2CAP Enhanced Credit Based Connection.
90 : *
91 : * This requirement is inferred from text in Core 3.A.4.25 v6.0:
92 : *
93 : * L2CAP implementations shall support a minimum MTU size of 64
94 : * octets for these channels.
95 : */
96 1 : #define BT_L2CAP_ECRED_MIN_MTU 64
97 :
98 : /** @brief L2CAP ECRED minimum MPS
99 : *
100 : * The minimum MPS for an L2CAP Enhanced Credit Based Connection.
101 : *
102 : * This requirement is inferred from text in Core 3.A.4.25 v6.0:
103 : *
104 : * L2CAP implementations shall support a minimum MPS of 64 and may
105 : * support an MPS up to 65533 octets for these channels.
106 : */
107 1 : #define BT_L2CAP_ECRED_MIN_MPS 64
108 :
109 : /** @brief The maximum number of channels in ECRED L2CAP signaling PDUs
110 : *
111 : * Currently, this is the maximum number of channels referred to in the
112 : * following PDUs:
113 : * - L2CAP_CREDIT_BASED_CONNECTION_REQ
114 : * - L2CAP_CREDIT_BASED_RECONFIGURE_REQ
115 : *
116 : * @warning The commonality is inferred between the PDUs. The Bluetooth
117 : * specification treats these as separate numbers and does now
118 : * guarantee the same limit for potential future ECRED L2CAP signaling
119 : * PDUs.
120 : */
121 1 : #define BT_L2CAP_ECRED_CHAN_MAX_PER_REQ 5
122 :
123 : struct bt_l2cap_chan;
124 :
125 : /** @typedef bt_l2cap_chan_destroy_t
126 : * @brief Channel destroy callback
127 : *
128 : * @param chan Channel object.
129 : */
130 1 : typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan);
131 :
132 : /** @brief Life-span states of L2CAP CoC channel.
133 : *
134 : * Used only by internal APIs dealing with setting channel to proper state
135 : * depending on operational context.
136 : *
137 : * A channel enters the @ref BT_L2CAP_CONNECTING state upon @ref
138 : * bt_l2cap_chan_connect, @ref bt_l2cap_ecred_chan_connect or upon returning
139 : * from @ref bt_l2cap_server.accept.
140 : *
141 : * When a channel leaves the @ref BT_L2CAP_CONNECTING state, @ref
142 : * bt_l2cap_chan_ops.connected is called.
143 : */
144 1 : typedef enum bt_l2cap_chan_state {
145 : /** Channel disconnected */
146 : BT_L2CAP_DISCONNECTED,
147 : /** Channel in connecting state */
148 : BT_L2CAP_CONNECTING,
149 : /** Channel in config state, BR/EDR specific */
150 : BT_L2CAP_CONFIG,
151 : /** Channel ready for upper layer traffic on it */
152 : BT_L2CAP_CONNECTED,
153 : /** Channel in disconnecting state */
154 : BT_L2CAP_DISCONNECTING,
155 :
156 1 : } __packed bt_l2cap_chan_state_t;
157 :
158 : /** @brief Status of L2CAP channel. */
159 0 : typedef enum bt_l2cap_chan_status {
160 : /** Channel can send at least one PDU */
161 : BT_L2CAP_STATUS_OUT,
162 :
163 : /** @brief Channel shutdown status
164 : *
165 : * Once this status is notified it means the channel will no longer be
166 : * able to transmit or receive data.
167 : */
168 : BT_L2CAP_STATUS_SHUTDOWN,
169 :
170 : /** @brief Channel encryption pending status */
171 : BT_L2CAP_STATUS_ENCRYPT_PENDING,
172 :
173 : /* Total number of status - must be at the end of the enum */
174 : BT_L2CAP_NUM_STATUS,
175 1 : } __packed bt_l2cap_chan_status_t;
176 :
177 : /** @brief L2CAP Channel structure. */
178 1 : struct bt_l2cap_chan {
179 : /** Channel connection reference */
180 1 : struct bt_conn *conn;
181 : /** Channel operations reference */
182 1 : const struct bt_l2cap_chan_ops *ops;
183 0 : sys_snode_t node;
184 0 : bt_l2cap_chan_destroy_t destroy;
185 :
186 0 : ATOMIC_DEFINE(status, BT_L2CAP_NUM_STATUS);
187 : };
188 :
189 : /** @brief LE L2CAP Endpoint structure. */
190 1 : struct bt_l2cap_le_endpoint {
191 : /** Endpoint Channel Identifier (CID) */
192 1 : uint16_t cid;
193 : /** Endpoint Maximum Transmission Unit */
194 1 : uint16_t mtu;
195 : /** Endpoint Maximum PDU payload Size */
196 1 : uint16_t mps;
197 : /** Endpoint credits */
198 1 : atomic_t credits;
199 : };
200 :
201 : /** @brief LE L2CAP Channel structure. */
202 1 : struct bt_l2cap_le_chan {
203 : /** Common L2CAP channel reference object */
204 1 : struct bt_l2cap_chan chan;
205 : /** @brief Channel Receiving Endpoint.
206 : *
207 : * If the application has set an alloc_buf channel callback for the
208 : * channel to support receiving segmented L2CAP SDUs the application
209 : * should initialize the MTU of the Receiving Endpoint. Otherwise the
210 : * MTU of the receiving endpoint will be initialized to
211 : * @ref BT_L2CAP_SDU_RX_MTU by the stack.
212 : *
213 : * This is the source of the MTU, MPS and credit values when sending
214 : * L2CAP_LE_CREDIT_BASED_CONNECTION_REQ/RSP and
215 : * L2CAP_CONFIGURATION_REQ.
216 : */
217 1 : struct bt_l2cap_le_endpoint rx;
218 :
219 : /** Pending RX MTU on ECFC reconfigure, used internally by stack */
220 1 : uint16_t pending_rx_mtu;
221 :
222 : /** Channel Transmission Endpoint.
223 : *
224 : * This is an image of the remote's rx.
225 : *
226 : * The MTU and MPS is controlled by the remote by
227 : * L2CAP_LE_CREDIT_BASED_CONNECTION_REQ/RSP or L2CAP_CONFIGURATION_REQ.
228 : */
229 1 : struct bt_l2cap_le_endpoint tx;
230 : /** Channel Transmission queue (for SDUs) */
231 1 : struct k_fifo tx_queue;
232 : #if defined(CONFIG_BT_L2CAP_DYNAMIC_CHANNEL)
233 : /** Segment SDU packet from upper layer */
234 : struct net_buf *_sdu;
235 : uint16_t _sdu_len;
236 : #if defined(CONFIG_BT_L2CAP_SEG_RECV)
237 : uint16_t _sdu_len_done;
238 : #endif /* CONFIG_BT_L2CAP_SEG_RECV */
239 :
240 : struct k_work rx_work;
241 : struct k_fifo rx_queue;
242 :
243 : bt_l2cap_chan_state_t state;
244 : /** Remote PSM to be connected */
245 : uint16_t psm;
246 : /** Helps match request context during CoC */
247 : uint8_t ident;
248 : bt_security_t required_sec_level;
249 :
250 : /* Response Timeout eXpired (RTX) timer */
251 : struct k_work_delayable rtx_work;
252 : struct k_work_sync rtx_sync;
253 : #endif
254 :
255 : /** @internal To be used with @ref bt_conn.upper_data_ready */
256 : sys_snode_t _pdu_ready;
257 : /** @internal To be used with @ref bt_conn.upper_data_ready */
258 : atomic_t _pdu_ready_lock;
259 : /** @internal Holds the length of the current PDU/segment */
260 : size_t _pdu_remaining;
261 : };
262 :
263 : /**
264 : * @brief Helper macro getting container object of type bt_l2cap_le_chan
265 : * address having the same container chan member address as object in question.
266 : *
267 : * @param _ch Address of object of bt_l2cap_chan type
268 : *
269 : * @return Address of in memory bt_l2cap_le_chan object type containing
270 : * the address of in question object.
271 : */
272 1 : #define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan)
273 :
274 : /** @brief BREDR L2CAP Endpoint structure. */
275 1 : struct bt_l2cap_br_endpoint {
276 : /** Endpoint Channel Identifier (CID) */
277 1 : uint16_t cid;
278 : /** Endpoint Maximum Transmission Unit */
279 1 : uint16_t mtu;
280 : };
281 :
282 : /** @brief BREDR L2CAP Channel structure. */
283 1 : struct bt_l2cap_br_chan {
284 : /** Common L2CAP channel reference object */
285 1 : struct bt_l2cap_chan chan;
286 : /** Channel Receiving Endpoint */
287 1 : struct bt_l2cap_br_endpoint rx;
288 : /** Channel Transmission Endpoint */
289 1 : struct bt_l2cap_br_endpoint tx;
290 : /* For internal use only */
291 0 : atomic_t flags[1];
292 :
293 0 : bt_l2cap_chan_state_t state;
294 : /** Remote PSM to be connected */
295 1 : uint16_t psm;
296 : /** Helps match request context during CoC */
297 1 : uint8_t ident;
298 0 : bt_security_t required_sec_level;
299 :
300 : /* Response Timeout eXpired (RTX) timer */
301 0 : struct k_work_delayable rtx_work;
302 0 : struct k_work_sync rtx_sync;
303 :
304 : /** @internal To be used with @ref bt_conn.upper_data_ready */
305 : sys_snode_t _pdu_ready;
306 : /** @internal To be used with @ref bt_conn.upper_data_ready */
307 : atomic_t _pdu_ready_lock;
308 : /** @internal Queue of net bufs not yet sent to lower layer */
309 : struct k_fifo _pdu_tx_queue;
310 : };
311 :
312 : /** @brief L2CAP Channel operations structure.
313 : *
314 : * The object has to stay valid and constant for the lifetime of the channel.
315 : */
316 1 : struct bt_l2cap_chan_ops {
317 : /** @brief Channel connected callback
318 : *
319 : * If this callback is provided it will be called whenever the
320 : * connection completes.
321 : *
322 : * @param chan The channel that has been connected
323 : */
324 1 : void (*connected)(struct bt_l2cap_chan *chan);
325 :
326 : /** @brief Channel disconnected callback
327 : *
328 : * If this callback is provided it will be called whenever the
329 : * channel is disconnected, including when a connection gets
330 : * rejected.
331 : *
332 : * @param chan The channel that has been Disconnected
333 : */
334 1 : void (*disconnected)(struct bt_l2cap_chan *chan);
335 :
336 : /** @brief Channel encrypt_change callback
337 : *
338 : * If this callback is provided it will be called whenever the
339 : * security level changed (indirectly link encryption done) or
340 : * authentication procedure fails. In both cases security initiator
341 : * and responder got the final status (HCI status) passed by
342 : * related to encryption and authentication events from local host's
343 : * controller.
344 : *
345 : * @param chan The channel which has made encryption status changed.
346 : * @param status HCI status of performed security procedure caused
347 : * by channel security requirements. The value is populated
348 : * by HCI layer and set to 0 when success and to non-zero (reference to
349 : * HCI Error Codes) when security/authentication failed.
350 : */
351 1 : void (*encrypt_change)(struct bt_l2cap_chan *chan, uint8_t hci_status);
352 :
353 : /** @brief Channel alloc_seg callback
354 : *
355 : * If this callback is provided the channel will use it to allocate
356 : * buffers to store segments. This avoids wasting big SDU buffers with
357 : * potentially much smaller PDUs. If this callback is supplied, it must
358 : * return a valid buffer.
359 : *
360 : * @param chan The channel requesting a buffer.
361 : *
362 : * @return Allocated buffer.
363 : */
364 : struct net_buf *(*alloc_seg)(struct bt_l2cap_chan *chan);
365 :
366 : /** @brief Channel alloc_buf callback
367 : *
368 : * If this callback is provided the channel will use it to allocate
369 : * buffers to store incoming data. Channels that requires segmentation
370 : * must set this callback.
371 : * If the application has not set a callback the L2CAP SDU MTU will be
372 : * truncated to @ref BT_L2CAP_SDU_RX_MTU.
373 : *
374 : * @param chan The channel requesting a buffer.
375 : *
376 : * @return Allocated buffer.
377 : */
378 : struct net_buf *(*alloc_buf)(struct bt_l2cap_chan *chan);
379 :
380 : /** @brief Channel recv callback
381 : *
382 : * @param chan The channel receiving data.
383 : * @param buf Buffer containing incoming data.
384 : *
385 : * @note This callback is mandatory, unless
386 : * @kconfig{CONFIG_BT_L2CAP_SEG_RECV} is enabled and seg_recv is
387 : * supplied.
388 : *
389 : * If the application returns @c -EINPROGRESS, the application takes
390 : * ownership of the reference in @p buf. (I.e. This pointer value can
391 : * simply be given to @ref bt_l2cap_chan_recv_complete without any
392 : * calls @ref net_buf_ref or @ref net_buf_unref.)
393 : *
394 : * @return 0 in case of success or negative value in case of error.
395 : * @return -EINPROGRESS in case where user has to confirm once the data
396 : * has been processed by calling
397 : * @ref bt_l2cap_chan_recv_complete passing back
398 : * the buffer received with its original user_data
399 : * which contains the number of segments/credits
400 : * used by the packet.
401 : */
402 1 : int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf);
403 :
404 : /** @brief Channel sent callback
405 : *
406 : * This callback will be called once the controller marks the SDU
407 : * as completed. When the controller does so is implementation
408 : * dependent. It could be after the SDU is enqueued for transmission,
409 : * or after it is sent on air.
410 : *
411 : * @param chan The channel which has sent data.
412 : */
413 1 : void (*sent)(struct bt_l2cap_chan *chan);
414 :
415 : /** @brief Channel status callback
416 : *
417 : * If this callback is provided it will be called whenever the
418 : * channel status changes.
419 : *
420 : * @param chan The channel which status changed
421 : * @param status The channel status
422 : */
423 1 : void (*status)(struct bt_l2cap_chan *chan, atomic_t *status);
424 :
425 : /* @brief Channel released callback
426 : *
427 : * If this callback is set it is called when the stack has release all
428 : * references to the channel object.
429 : */
430 0 : void (*released)(struct bt_l2cap_chan *chan);
431 :
432 : /** @brief Channel reconfigured callback
433 : *
434 : * If this callback is provided it will be called whenever peer or
435 : * local device requested reconfiguration. Application may check
436 : * updated MTU and MPS values by inspecting chan->le endpoints.
437 : *
438 : * @param chan The channel which was reconfigured
439 : */
440 1 : void (*reconfigured)(struct bt_l2cap_chan *chan);
441 :
442 : #if defined(CONFIG_BT_L2CAP_SEG_RECV)
443 : /** @brief Handle L2CAP segments directly
444 : *
445 : * This is an alternative to @ref bt_l2cap_chan_ops.recv. They cannot
446 : * be used together.
447 : *
448 : * This is called immediately for each received segment.
449 : *
450 : * Unlike with @ref bt_l2cap_chan_ops.recv, flow control is explicit.
451 : * Each time this handler is invoked, the remote has permanently used
452 : * up one credit. Use @ref bt_l2cap_chan_give_credits to give credits.
453 : *
454 : * The start of an SDU is marked by `seg_offset == 0`. The end of an
455 : * SDU is marked by `seg_offset + seg->len == sdu_len`.
456 : *
457 : * The stack guarantees that:
458 : * - The sender had the credit.
459 : * - The SDU length does not exceed MTU.
460 : * - The segment length does not exceed MPS.
461 : *
462 : * Additionally, the L2CAP protocol is such that:
463 : * - Segments come in order.
464 : * - SDUs cannot be interleaved or aborted halfway.
465 : *
466 : * @note With this alternative API, the application is responsible for
467 : * setting the RX MTU and MPS. The MPS must not exceed @ref BT_L2CAP_RX_MTU.
468 : *
469 : * @param chan The receiving channel.
470 : * @param sdu_len Byte length of the SDU this segment is part of.
471 : * @param seg_offset The byte offset of this segment in the SDU.
472 : * @param seg The segment payload.
473 : */
474 1 : void (*seg_recv)(struct bt_l2cap_chan *chan, size_t sdu_len,
475 : off_t seg_offset, struct net_buf_simple *seg);
476 : #endif /* CONFIG_BT_L2CAP_SEG_RECV */
477 : };
478 :
479 : /**
480 : * @brief Headroom needed for outgoing L2CAP PDUs.
481 : */
482 1 : #define BT_L2CAP_CHAN_SEND_RESERVE (BT_L2CAP_BUF_SIZE(0))
483 :
484 : /**
485 : * @brief Headroom needed for outgoing L2CAP SDUs.
486 : */
487 1 : #define BT_L2CAP_SDU_CHAN_SEND_RESERVE (BT_L2CAP_SDU_BUF_SIZE(0))
488 :
489 : /** @brief L2CAP Server structure. */
490 1 : struct bt_l2cap_server {
491 : /** @brief Server PSM.
492 : *
493 : * Possible values:
494 : * 0 A dynamic value will be auto-allocated when
495 : * bt_l2cap_server_register() is called.
496 : *
497 : * 0x0001-0x007f Standard, Bluetooth SIG-assigned fixed values.
498 : *
499 : * 0x0080-0x00ff Dynamically allocated. May be pre-set by the
500 : * application before server registration (not
501 : * recommended however), or auto-allocated by the
502 : * stack if the app gave 0 as the value.
503 : */
504 1 : uint16_t psm;
505 :
506 : /** Required minimum security level */
507 1 : bt_security_t sec_level;
508 :
509 : /** @brief Server accept callback
510 : *
511 : * This callback is called whenever a new incoming connection requires
512 : * authorization.
513 : *
514 : * @warning It is the responsibility of this callback to zero out the
515 : * parent of the chan object.
516 : *
517 : * @param conn The connection that is requesting authorization
518 : * @param server Pointer to the server structure this callback relates to
519 : * @param chan Pointer to received the allocated channel
520 : *
521 : * @return 0 in case of success or negative value in case of error.
522 : * @return -ENOMEM if no available space for new channel.
523 : * @return -EACCES if application did not authorize the connection.
524 : * @return -EPERM if encryption key size is too short.
525 : */
526 1 : int (*accept)(struct bt_conn *conn, struct bt_l2cap_server *server,
527 : struct bt_l2cap_chan **chan);
528 :
529 0 : sys_snode_t node;
530 : };
531 :
532 : /** @brief Register L2CAP server.
533 : *
534 : * Register L2CAP server for a PSM, each new connection is authorized using
535 : * the accept() callback which in case of success shall allocate the channel
536 : * structure to be used by the new connection.
537 : *
538 : * For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should
539 : * be assigned to server->psm before calling this API. For dynamic PSMs
540 : * (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value
541 : * (this is however not recommended) or be left as 0, in which case upon
542 : * return a newly allocated value will have been assigned to it. For
543 : * dynamically allocated values the expectation is that it's exposed through
544 : * a GATT service, and that's how L2CAP clients discover how to connect to
545 : * the server.
546 : *
547 : * @param server Server structure.
548 : *
549 : * @return 0 in case of success or negative value in case of error.
550 : */
551 1 : int bt_l2cap_server_register(struct bt_l2cap_server *server);
552 :
553 : /** @brief Register L2CAP server on BR/EDR oriented connection.
554 : *
555 : * Register L2CAP server for a PSM, each new connection is authorized using
556 : * the accept() callback which in case of success shall allocate the channel
557 : * structure to be used by the new connection.
558 : *
559 : * @param server Server structure.
560 : *
561 : * @return 0 in case of success or negative value in case of error.
562 : */
563 1 : int bt_l2cap_br_server_register(struct bt_l2cap_server *server);
564 :
565 : /** @brief Connect Enhanced Credit Based L2CAP channels
566 : *
567 : * Connect up to 5 L2CAP channels by PSM, once the connection is completed
568 : * each channel connected() callback will be called. If the connection is
569 : * rejected disconnected() callback is called instead.
570 : *
571 : * @warning It is the responsibility of the caller to zero out the
572 : * parents of the chan objects.
573 : *
574 : * @param conn Connection object.
575 : * @param chans Array of channel objects.
576 : * @param psm Channel PSM to connect to.
577 : *
578 : * @return 0 in case of success or negative value in case of error.
579 : */
580 1 : int bt_l2cap_ecred_chan_connect(struct bt_conn *conn,
581 : struct bt_l2cap_chan **chans, uint16_t psm);
582 :
583 : /** @brief Reconfigure Enhanced Credit Based L2CAP channels
584 : *
585 : * Reconfigure up to 5 L2CAP channels. Channels must be from the same bt_conn.
586 : * Once reconfiguration is completed each channel reconfigured() callback will
587 : * be called. MTU cannot be decreased on any of provided channels.
588 : *
589 : * @param chans Array of channel objects. Null-terminated. Elements after the
590 : * first 5 are silently ignored.
591 : * @param mtu Channel MTU to reconfigure to.
592 : *
593 : * @return 0 in case of success or negative value in case of error.
594 : */
595 1 : int bt_l2cap_ecred_chan_reconfigure(struct bt_l2cap_chan **chans, uint16_t mtu);
596 :
597 : /** @brief Reconfigure Enhanced Credit Based L2CAP channels
598 : *
599 : * Experimental API to reconfigure L2CAP ECRED channels with explicit MPS and
600 : * MTU values.
601 : *
602 : * Pend a L2CAP ECRED reconfiguration for up to 5 channels. All provided
603 : * channels must share the same @ref bt_conn.
604 : *
605 : * This API cannot decrease the MTU of any channel, and it cannot decrease the
606 : * MPS of any channel when more than one channel is provided.
607 : *
608 : * There is no dedicated callback for this operation, but whenever a peer
609 : * responds to a reconfiguration request, each affected channel's
610 : * reconfigured() callback is invoked.
611 : *
612 : * This function may block.
613 : *
614 : * @warning Known issue: The implementation returns -EBUSY if there already is
615 : * an ongoing reconfigure operation on the same connection. The caller may try
616 : * again later. There is no event signaling when the existing operation
617 : * finishes.
618 : *
619 : * @warning Known issue: The implementation returns -ENOMEM when unable to
620 : * allocate. The caller may try again later. There is no event signaling the
621 : * availability of buffers.
622 : *
623 : * @kconfig_dep{CONFIG_BT_L2CAP_RECONFIGURE_EXPLICIT}
624 : *
625 : * @param chans Array of channels to reconfigure. Must be non-empty and
626 : * contain at most 5 (@ref BT_L2CAP_ECRED_CHAN_MAX_PER_REQ)
627 : * elements.
628 : * @param chan_count Number of channels in the array.
629 : * @param mtu Desired MTU. Must be at least @ref BT_L2CAP_ECRED_MIN_MTU.
630 : * @param mps Desired MPS. Must be in range @ref BT_L2CAP_ECRED_MIN_MPS
631 : * to @ref BT_L2CAP_RX_MTU.
632 : *
633 : * @retval 0 Successfully pended operation.
634 : * @retval -EINVAL Bad arguments. See above requirements.
635 : * @retval -ENOTCONN Connection object is not in connected state.
636 : * @retval -EBUSY Another outgoing reconfiguration is pending on the same
637 : * connection.
638 : * @retval -ENOMEM Host is out of buffers.
639 : */
640 1 : int bt_l2cap_ecred_chan_reconfigure_explicit(struct bt_l2cap_chan **chans, size_t chan_count,
641 : uint16_t mtu, uint16_t mps);
642 :
643 : /** @brief Connect L2CAP channel
644 : *
645 : * Connect L2CAP channel by PSM, once the connection is completed channel
646 : * connected() callback will be called. If the connection is rejected
647 : * disconnected() callback is called instead.
648 : * Channel object passed (over an address of it) as second parameter shouldn't
649 : * be instantiated in application as standalone. Instead of, application should
650 : * create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for
651 : * LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API
652 : * the location (address) of bt_l2cap_chan type object which is a member
653 : * of both transport dedicated objects.
654 : *
655 : * @warning It is the responsibility of the caller to zero out the
656 : * parent of the chan object.
657 : *
658 : * @param conn Connection object.
659 : * @param chan Channel object.
660 : * @param psm Channel PSM to connect to.
661 : *
662 : * @return 0 in case of success or negative value in case of error.
663 : */
664 1 : int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan,
665 : uint16_t psm);
666 :
667 : /** @brief Disconnect L2CAP channel
668 : *
669 : * Disconnect L2CAP channel, if the connection is pending it will be
670 : * canceled and as a result the channel disconnected() callback is called.
671 : * Regarding to input parameter, to get details see reference description
672 : * to bt_l2cap_chan_connect() API above.
673 : *
674 : * @param chan Channel object.
675 : *
676 : * @return 0 in case of success or negative value in case of error.
677 : */
678 1 : int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan);
679 :
680 : /** @brief Send data to L2CAP channel
681 : *
682 : * Send data from buffer to the channel. If credits are not available, buf will
683 : * be queued and sent as and when credits are received from peer.
684 : * Regarding to first input parameter, to get details see reference description
685 : * to bt_l2cap_chan_connect() API above.
686 : *
687 : * Network buffer fragments (ie `buf->frags`) are not supported.
688 : *
689 : * When sending L2CAP data over an BR/EDR connection the application is sending
690 : * L2CAP PDUs. The application is required to have reserved
691 : * @ref BT_L2CAP_CHAN_SEND_RESERVE bytes in the buffer before sending.
692 : * The application should use the BT_L2CAP_BUF_SIZE() helper to correctly
693 : * size the buffers for the for the outgoing buffer pool.
694 : *
695 : * When sending L2CAP data over an LE connection the application is sending
696 : * L2CAP SDUs. The application shall reserve
697 : * @ref BT_L2CAP_SDU_CHAN_SEND_RESERVE bytes in the buffer before sending.
698 : *
699 : * The application can use the BT_L2CAP_SDU_BUF_SIZE() helper to correctly size
700 : * the buffer to account for the reserved headroom.
701 : *
702 : * When segmenting an L2CAP SDU into L2CAP PDUs the stack will first attempt to
703 : * allocate buffers from the channel's `alloc_seg` callback and will fallback
704 : * on the stack's global buffer pool (sized
705 : * @kconfig{CONFIG_BT_L2CAP_TX_BUF_COUNT}).
706 : *
707 : * @warning The buffer's user_data _will_ be overwritten by this function. Do
708 : * not store anything in it. As soon as a call to this function has been made,
709 : * consider ownership of user_data transferred into the stack.
710 : *
711 : * @note Buffer ownership is transferred to the stack in case of success, in
712 : * case of an error the caller retains the ownership of the buffer.
713 : *
714 : * @return 0 in case of success or negative value in case of error.
715 : * @return -EINVAL if `buf` or `chan` is NULL.
716 : * @return -EINVAL if `chan` is not either BR/EDR or LE credit-based.
717 : * @return -EINVAL if buffer doesn't have enough bytes reserved to fit header.
718 : * @return -EINVAL if buffer's reference counter != 1
719 : * @return -EMSGSIZE if `buf` is larger than `chan`'s MTU.
720 : * @return -ENOTCONN if underlying conn is disconnected.
721 : * @return -ESHUTDOWN if L2CAP channel is disconnected.
722 : * @return -other (from lower layers) if chan is BR/EDR.
723 : */
724 1 : int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf);
725 :
726 : /** @brief Give credits to the remote
727 : *
728 : * Only available for channels using @ref bt_l2cap_chan_ops.seg_recv.
729 : * @kconfig{CONFIG_BT_L2CAP_SEG_RECV} must be enabled to make this function
730 : * available.
731 : *
732 : * Each credit given allows the peer to send one segment.
733 : *
734 : * This function depends on a valid @p chan object. Make sure to
735 : * default-initialize or memset @p chan when allocating or reusing it for new
736 : * connections.
737 : *
738 : * Adding zero credits is not allowed.
739 : *
740 : * Credits can be given before entering the @ref BT_L2CAP_CONNECTING state.
741 : * Doing so will adjust the 'initial credits' sent in the connection PDU.
742 : *
743 : * Must not be called while the channel is in @ref BT_L2CAP_CONNECTING state.
744 : *
745 : * @return 0 in case of success or negative value in case of error.
746 : */
747 1 : int bt_l2cap_chan_give_credits(struct bt_l2cap_chan *chan, uint16_t additional_credits);
748 :
749 : /** @brief Complete receiving L2CAP channel data
750 : *
751 : * Complete the reception of incoming data. This shall only be called if the
752 : * channel recv callback has returned -EINPROGRESS to process some incoming
753 : * data. The buffer shall contain the original user_data as that is used for
754 : * storing the credits/segments used by the packet.
755 : *
756 : * @param chan Channel object.
757 : * @param buf Buffer containing the data.
758 : *
759 : * @return 0 in case of success or negative value in case of error.
760 : */
761 1 : int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan,
762 : struct net_buf *buf);
763 :
764 : #ifdef __cplusplus
765 : }
766 : #endif
767 :
768 : /**
769 : * @}
770 : */
771 :
772 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ */
|
