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 #define BT_L2CAP_HDR_SIZE 4 35 36 /** Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU. */ 37 #define BT_L2CAP_TX_MTU (CONFIG_BT_L2CAP_TX_MTU) 38 39 /** Maximum Transmission Unit (MTU) for an incoming L2CAP PDU. */ 40 #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 #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 #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 #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 #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 #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 #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 #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 #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 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 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 } __packed bt_l2cap_chan_state_t; 157 158 /** @brief Status of L2CAP channel. */ 159 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 } __packed bt_l2cap_chan_status_t; 176 177 /** @brief L2CAP Channel structure. */ 178 struct bt_l2cap_chan { 179 /** Channel connection reference */ 180 struct bt_conn *conn; 181 /** Channel operations reference */ 182 const struct bt_l2cap_chan_ops *ops; 183 sys_snode_t node; 184 bt_l2cap_chan_destroy_t destroy; 185 186 ATOMIC_DEFINE(status, BT_L2CAP_NUM_STATUS); 187 }; 188 189 /** @brief LE L2CAP Endpoint structure. */ 190 struct bt_l2cap_le_endpoint { 191 /** Endpoint Channel Identifier (CID) */ 192 uint16_t cid; 193 /** Endpoint Maximum Transmission Unit */ 194 uint16_t mtu; 195 /** Endpoint Maximum PDU payload Size */ 196 uint16_t mps; 197 /** Endpoint credits */ 198 atomic_t credits; 199 }; 200 201 /** @brief LE L2CAP Channel structure. */ 202 struct bt_l2cap_le_chan { 203 /** Common L2CAP channel reference object */ 204 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 struct bt_l2cap_le_endpoint rx; 218 219 /** Pending RX MTU on ECFC reconfigure, used internally by stack */ 220 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 struct bt_l2cap_le_endpoint tx; 230 /** Channel Transmission queue (for SDUs) */ 231 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 #define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan) 273 274 /** @brief BREDR L2CAP Endpoint structure. */ 275 struct bt_l2cap_br_endpoint { 276 /** Endpoint Channel Identifier (CID) */ 277 uint16_t cid; 278 /** Endpoint Maximum Transmission Unit */ 279 uint16_t mtu; 280 }; 281 282 /** @brief BREDR L2CAP Channel structure. */ 283 struct bt_l2cap_br_chan { 284 /** Common L2CAP channel reference object */ 285 struct bt_l2cap_chan chan; 286 /** Channel Receiving Endpoint */ 287 struct bt_l2cap_br_endpoint rx; 288 /** Channel Transmission Endpoint */ 289 struct bt_l2cap_br_endpoint tx; 290 /* For internal use only */ 291 atomic_t flags[1]; 292 293 bt_l2cap_chan_state_t state; 294 /** Remote PSM to be connected */ 295 uint16_t psm; 296 /** Helps match request context during CoC */ 297 uint8_t ident; 298 bt_security_t required_sec_level; 299 300 /* Response Timeout eXpired (RTX) timer */ 301 struct k_work_delayable rtx_work; 302 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 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 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 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 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 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 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 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 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 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 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 #define BT_L2CAP_CHAN_SEND_RESERVE (BT_L2CAP_BUF_SIZE(0)) 483 484 /** 485 * @brief Headroom needed for outgoing L2CAP SDUs. 486 */ 487 #define BT_L2CAP_SDU_CHAN_SEND_RESERVE (BT_L2CAP_SDU_BUF_SIZE(0)) 488 489 /** @brief L2CAP Server structure. */ 490 struct bt_l2cap_server { 491 /** @brief Server PSM. 492 * 493 * For LE, 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 * For BR, possible values: 505 * 506 * The PSM field is at least two octets in length. All PSM values shall have the least 507 * significant bit of the most significant octet equal to 0 and the least significant bit 508 * of all other octets equal to 1. 509 * 510 * 0 A dynamic value will be auto-allocated when 511 * bt_l2cap_br_server_register() is called. 512 * 513 * 0x0001-0x0eff Standard, Bluetooth SIG-assigned fixed values. 514 * 515 * > 0x1000 Dynamically allocated. May be pre-set by the 516 * application before server registration (not 517 * recommended however), or auto-allocated by the 518 * stack if the app gave 0 as the value. 519 */ 520 uint16_t psm; 521 522 /** Required minimum security level */ 523 bt_security_t sec_level; 524 525 /** @brief Server accept callback 526 * 527 * This callback is called whenever a new incoming connection requires 528 * authorization. 529 * 530 * @warning It is the responsibility of this callback to zero out the 531 * parent of the chan object. 532 * 533 * @param conn The connection that is requesting authorization 534 * @param server Pointer to the server structure this callback relates to 535 * @param chan Pointer to received the allocated channel 536 * 537 * @return 0 in case of success or negative value in case of error. 538 * @return -ENOMEM if no available space for new channel. 539 * @return -EACCES if application did not authorize the connection. 540 * @return -EPERM if encryption key size is too short. 541 */ 542 int (*accept)(struct bt_conn *conn, struct bt_l2cap_server *server, 543 struct bt_l2cap_chan **chan); 544 545 sys_snode_t node; 546 }; 547 548 /** @brief Register L2CAP server. 549 * 550 * Register L2CAP server for a PSM, each new connection is authorized using 551 * the accept() callback which in case of success shall allocate the channel 552 * structure to be used by the new connection. 553 * 554 * For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should 555 * be assigned to server->psm before calling this API. For dynamic PSMs 556 * (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value 557 * (this is however not recommended) or be left as 0, in which case upon 558 * return a newly allocated value will have been assigned to it. For 559 * dynamically allocated values the expectation is that it's exposed through 560 * a GATT service, and that's how L2CAP clients discover how to connect to 561 * the server. 562 * 563 * @param server Server structure. 564 * 565 * @return 0 in case of success or negative value in case of error. 566 */ 567 int bt_l2cap_server_register(struct bt_l2cap_server *server); 568 569 /** @brief Register L2CAP server on BR/EDR oriented connection. 570 * 571 * Register L2CAP server for a PSM, each new connection is authorized using 572 * the accept() callback which in case of success shall allocate the channel 573 * structure to be used by the new connection. 574 * 575 * For fixed, SIG-assigned PSMs (in the range 0x0001-0x0eff) the PSM should 576 * be assigned to server->psm before calling this API. For dynamic PSMs 577 * (in the range 0x1000-0xffff) server->psm may be pre-set to a given value 578 * (this is however not recommended) or be left as 0, in which case upon 579 * return a newly allocated value will have been assigned to it. For 580 * dynamically allocated values the expectation is that it's exposed through 581 * a SDP record, and that's how L2CAP clients discover how to connect to 582 * the server. 583 * 584 * @param server Server structure. 585 * 586 * @return 0 in case of success or negative value in case of error. 587 */ 588 int bt_l2cap_br_server_register(struct bt_l2cap_server *server); 589 590 /** @brief Connect Enhanced Credit Based L2CAP channels 591 * 592 * Connect up to 5 L2CAP channels by PSM, once the connection is completed 593 * each channel connected() callback will be called. If the connection is 594 * rejected disconnected() callback is called instead. 595 * 596 * @warning It is the responsibility of the caller to zero out the 597 * parents of the chan objects. 598 * 599 * @param conn Connection object. 600 * @param chans Array of channel objects. 601 * @param psm Channel PSM to connect to. 602 * 603 * @return 0 in case of success or negative value in case of error. 604 */ 605 int bt_l2cap_ecred_chan_connect(struct bt_conn *conn, 606 struct bt_l2cap_chan **chans, uint16_t psm); 607 608 /** @brief Reconfigure Enhanced Credit Based L2CAP channels 609 * 610 * Reconfigure up to 5 L2CAP channels. Channels must be from the same bt_conn. 611 * Once reconfiguration is completed each channel reconfigured() callback will 612 * be called. MTU cannot be decreased on any of provided channels. 613 * 614 * @param chans Array of channel objects. Null-terminated. Elements after the 615 * first 5 are silently ignored. 616 * @param mtu Channel MTU to reconfigure to. 617 * 618 * @return 0 in case of success or negative value in case of error. 619 */ 620 int bt_l2cap_ecred_chan_reconfigure(struct bt_l2cap_chan **chans, uint16_t mtu); 621 622 /** @brief Reconfigure Enhanced Credit Based L2CAP channels 623 * 624 * Experimental API to reconfigure L2CAP ECRED channels with explicit MPS and 625 * MTU values. 626 * 627 * Pend a L2CAP ECRED reconfiguration for up to 5 channels. All provided 628 * channels must share the same @ref bt_conn. 629 * 630 * This API cannot decrease the MTU of any channel, and it cannot decrease the 631 * MPS of any channel when more than one channel is provided. 632 * 633 * There is no dedicated callback for this operation, but whenever a peer 634 * responds to a reconfiguration request, each affected channel's 635 * reconfigured() callback is invoked. 636 * 637 * This function may block. 638 * 639 * @warning Known issue: The implementation returns -EBUSY if there already is 640 * an ongoing reconfigure operation on the same connection. The caller may try 641 * again later. There is no event signaling when the existing operation 642 * finishes. 643 * 644 * @warning Known issue: The implementation returns -ENOMEM when unable to 645 * allocate. The caller may try again later. There is no event signaling the 646 * availability of buffers. 647 * 648 * @kconfig_dep{CONFIG_BT_L2CAP_RECONFIGURE_EXPLICIT} 649 * 650 * @param chans Array of channels to reconfigure. Must be non-empty and 651 * contain at most 5 (@ref BT_L2CAP_ECRED_CHAN_MAX_PER_REQ) 652 * elements. 653 * @param chan_count Number of channels in the array. 654 * @param mtu Desired MTU. Must be at least @ref BT_L2CAP_ECRED_MIN_MTU. 655 * @param mps Desired MPS. Must be in range @ref BT_L2CAP_ECRED_MIN_MPS 656 * to @ref BT_L2CAP_RX_MTU. 657 * 658 * @retval 0 Successfully pended operation. 659 * @retval -EINVAL Bad arguments. See above requirements. 660 * @retval -ENOTCONN Connection object is not in connected state. 661 * @retval -EBUSY Another outgoing reconfiguration is pending on the same 662 * connection. 663 * @retval -ENOMEM Host is out of buffers. 664 */ 665 int bt_l2cap_ecred_chan_reconfigure_explicit(struct bt_l2cap_chan **chans, size_t chan_count, 666 uint16_t mtu, uint16_t mps); 667 668 /** @brief Connect L2CAP channel 669 * 670 * Connect L2CAP channel by PSM, once the connection is completed channel 671 * connected() callback will be called. If the connection is rejected 672 * disconnected() callback is called instead. 673 * Channel object passed (over an address of it) as second parameter shouldn't 674 * be instantiated in application as standalone. Instead of, application should 675 * create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for 676 * LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API 677 * the location (address) of bt_l2cap_chan type object which is a member 678 * of both transport dedicated objects. 679 * 680 * @warning It is the responsibility of the caller to zero out the 681 * parent of the chan object. 682 * 683 * @param conn Connection object. 684 * @param chan Channel object. 685 * @param psm Channel PSM to connect to. 686 * 687 * @return 0 in case of success or negative value in case of error. 688 */ 689 int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan, 690 uint16_t psm); 691 692 /** @brief Disconnect L2CAP channel 693 * 694 * Disconnect L2CAP channel, if the connection is pending it will be 695 * canceled and as a result the channel disconnected() callback is called. 696 * Regarding to input parameter, to get details see reference description 697 * to bt_l2cap_chan_connect() API above. 698 * 699 * @param chan Channel object. 700 * 701 * @return 0 in case of success or negative value in case of error. 702 */ 703 int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan); 704 705 /** @brief Send data to L2CAP channel 706 * 707 * Send data from buffer to the channel. If credits are not available, buf will 708 * be queued and sent as and when credits are received from peer. 709 * Regarding to first input parameter, to get details see reference description 710 * to bt_l2cap_chan_connect() API above. 711 * 712 * Network buffer fragments (ie `buf->frags`) are not supported. 713 * 714 * When sending L2CAP data over an BR/EDR connection the application is sending 715 * L2CAP PDUs. The application is required to have reserved 716 * @ref BT_L2CAP_CHAN_SEND_RESERVE bytes in the buffer before sending. 717 * The application should use the BT_L2CAP_BUF_SIZE() helper to correctly 718 * size the buffers for the for the outgoing buffer pool. 719 * 720 * When sending L2CAP data over an LE connection the application is sending 721 * L2CAP SDUs. The application shall reserve 722 * @ref BT_L2CAP_SDU_CHAN_SEND_RESERVE bytes in the buffer before sending. 723 * 724 * The application can use the BT_L2CAP_SDU_BUF_SIZE() helper to correctly size 725 * the buffer to account for the reserved headroom. 726 * 727 * When segmenting an L2CAP SDU into L2CAP PDUs the stack will first attempt to 728 * allocate buffers from the channel's `alloc_seg` callback and will fallback 729 * on the stack's global buffer pool (sized 730 * @kconfig{CONFIG_BT_L2CAP_TX_BUF_COUNT}). 731 * 732 * @warning The buffer's user_data _will_ be overwritten by this function. Do 733 * not store anything in it. As soon as a call to this function has been made, 734 * consider ownership of user_data transferred into the stack. 735 * 736 * @note Buffer ownership is transferred to the stack in case of success, in 737 * case of an error the caller retains the ownership of the buffer. 738 * 739 * @return 0 in case of success or negative value in case of error. 740 * @return -EINVAL if `buf` or `chan` is NULL. 741 * @return -EINVAL if `chan` is not either BR/EDR or LE credit-based. 742 * @return -EINVAL if buffer doesn't have enough bytes reserved to fit header. 743 * @return -EINVAL if buffer's reference counter != 1 744 * @return -EMSGSIZE if `buf` is larger than `chan`'s MTU. 745 * @return -ENOTCONN if underlying conn is disconnected. 746 * @return -ESHUTDOWN if L2CAP channel is disconnected. 747 * @return -other (from lower layers) if chan is BR/EDR. 748 */ 749 int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf); 750 751 /** @brief Give credits to the remote 752 * 753 * Only available for channels using @ref bt_l2cap_chan_ops.seg_recv. 754 * @kconfig{CONFIG_BT_L2CAP_SEG_RECV} must be enabled to make this function 755 * available. 756 * 757 * Each credit given allows the peer to send one segment. 758 * 759 * This function depends on a valid @p chan object. Make sure to 760 * default-initialize or memset @p chan when allocating or reusing it for new 761 * connections. 762 * 763 * Adding zero credits is not allowed. 764 * 765 * Credits can be given before entering the @ref BT_L2CAP_CONNECTING state. 766 * Doing so will adjust the 'initial credits' sent in the connection PDU. 767 * 768 * Must not be called while the channel is in @ref BT_L2CAP_CONNECTING state. 769 * 770 * @return 0 in case of success or negative value in case of error. 771 */ 772 int bt_l2cap_chan_give_credits(struct bt_l2cap_chan *chan, uint16_t additional_credits); 773 774 /** @brief Complete receiving L2CAP channel data 775 * 776 * Complete the reception of incoming data. This shall only be called if the 777 * channel recv callback has returned -EINPROGRESS to process some incoming 778 * data. The buffer shall contain the original user_data as that is used for 779 * storing the credits/segments used by the packet. 780 * 781 * @param chan Channel object. 782 * @param buf Buffer containing the data. 783 * 784 * @return 0 in case of success or negative value in case of error. 785 */ 786 int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan, 787 struct net_buf *buf); 788 789 #ifdef __cplusplus 790 } 791 #endif 792 793 /** 794 * @} 795 */ 796 797 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ */ 798
