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 * 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 uint16_t psm; 505 506 /** Required minimum security level */ 507 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 int (*accept)(struct bt_conn *conn, struct bt_l2cap_server *server, 527 struct bt_l2cap_chan **chan); 528 529 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 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 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 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 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 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 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 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 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 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 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_ */ 773
