1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title L2CAP 40 * 41 * Logical Link Control and Adaption Protocol 42 * 43 */ 44 45 #ifndef L2CAP_H 46 #define L2CAP_H 47 48 #include "hci.h" 49 #include "l2cap_signaling.h" 50 #include "btstack_util.h" 51 #include "bluetooth.h" 52 53 #if defined __cplusplus 54 extern "C" { 55 #endif 56 57 // check L2CAP MTU 58 #ifdef ENABLE_CLASSIC 59 #if (L2CAP_HEADER_SIZE + L2CAP_MINIMAL_MTU) > HCI_ACL_PAYLOAD_SIZE 60 #error "HCI_ACL_PAYLOAD_SIZE too small for minimal L2CAP MTU of 48 bytes" 61 #endif 62 #endif 63 #ifdef ENABLE_BLE 64 #if (L2CAP_HEADER_SIZE + L2CAP_LE_DEFAULT_MTU) > HCI_ACL_PAYLOAD_SIZE 65 #error "HCI_ACL_PAYLOAD_SIZE too small for minimal L2CAP LE MTU of 23 bytes" 66 #endif 67 #endif 68 69 #define L2CAP_LE_AUTOMATIC_CREDITS 0xffff 70 71 // private structs 72 typedef enum { 73 L2CAP_STATE_CLOSED = 1, // no baseband 74 L2CAP_STATE_WILL_SEND_CREATE_CONNECTION, 75 L2CAP_STATE_WAIT_CONNECTION_COMPLETE, 76 L2CAP_STATE_WAIT_REMOTE_SUPPORTED_FEATURES, 77 L2CAP_STATE_WAIT_INCOMING_SECURITY_LEVEL_UPDATE, 78 L2CAP_STATE_WAIT_OUTGOING_SECURITY_LEVEL_UPDATE, 79 L2CAP_STATE_WAIT_INCOMING_EXTENDED_FEATURES, // only for Enhanced Retransmission Mode 80 L2CAP_STATE_WAIT_OUTGOING_EXTENDED_FEATURES, // only for Enhanced Retransmission Mode 81 L2CAP_STATE_WAIT_CLIENT_ACCEPT_OR_REJECT, 82 L2CAP_STATE_WAIT_CONNECT_RSP, // from peer 83 L2CAP_STATE_CONFIG, 84 L2CAP_STATE_OPEN, 85 L2CAP_STATE_WAIT_DISCONNECT, // from application 86 L2CAP_STATE_WILL_SEND_CONNECTION_REQUEST, 87 L2CAP_STATE_WILL_SEND_CONNECTION_RESPONSE_INSUFFICIENT_SECURITY, 88 L2CAP_STATE_WILL_SEND_CONNECTION_RESPONSE_DECLINE, 89 L2CAP_STATE_WILL_SEND_CONNECTION_RESPONSE_ACCEPT, 90 L2CAP_STATE_WILL_SEND_DISCONNECT_REQUEST, 91 L2CAP_STATE_WILL_SEND_DISCONNECT_RESPONSE, 92 L2CAP_STATE_WILL_SEND_LE_CONNECTION_REQUEST, 93 L2CAP_STATE_WILL_SEND_LE_CONNECTION_RESPONSE_DECLINE, 94 L2CAP_STATE_WILL_SEND_LE_CONNECTION_RESPONSE_ACCEPT, 95 L2CAP_STATE_WAIT_LE_CONNECTION_RESPONSE, 96 L2CAP_STATE_EMIT_OPEN_FAILED_AND_DISCARD, 97 L2CAP_STATE_WILL_SEND_ENHANCED_CONNECTION_REQUEST, 98 L2CAP_STATE_WAIT_ENHANCED_CONNECTION_RESPONSE, 99 L2CAP_STATE_WILL_SEND_ENHANCED_CONNECTION_RESPONSE, 100 L2CAP_STATE_WILL_SEND_EHNANCED_RENEGOTIATION_REQUEST, 101 L2CAP_STATE_WAIT_ENHANCED_RENEGOTIATION_RESPONSE, 102 L2CAP_STATE_INVALID, 103 } L2CAP_STATE; 104 105 #define L2CAP_CHANNEL_STATE_VAR_NONE 0 106 #define L2CAP_CHANNEL_STATE_VAR_RCVD_CONF_REQ 1 << 0 107 #define L2CAP_CHANNEL_STATE_VAR_RCVD_CONF_RSP 1 << 1 108 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_REQ 1 << 2 109 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP 1 << 3 110 #define L2CAP_CHANNEL_STATE_VAR_SENT_CONF_REQ 1 << 4 111 #define L2CAP_CHANNEL_STATE_VAR_SENT_CONF_RSP 1 << 5 112 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_MTU 1 << 6 // in CONF RSP, add MTU option 113 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_ERTM 1 << 7 // in CONF RSP, add Retransmission and Flowcontrol option 114 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_CONT 1 << 8 // in CONF RSP, set CONTINUE flag 115 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_INVALID 1 << 9 // in CONF RSP, send UNKNOWN OPTIONS 116 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONF_RSP_REJECTED 1 << 10 // in CONF RSP, send Unacceptable Parameters (ERTM) 117 #define L2CAP_CHANNEL_STATE_VAR_BASIC_FALLBACK_TRIED 1 << 11 // set when ERTM was requested but we want only Basic mode (ERM) 118 #define L2CAP_CHANNEL_STATE_VAR_SEND_CONN_RESP_PEND 1 << 12 // send Connection Respond with pending 119 #define L2CAP_CHANNEL_STATE_VAR_SENT_CONN_RESP_PEND 1 << 13 // send CMD_REJ with reason unknown 120 #define L2CAP_CHANNEL_STATE_VAR_INCOMING 1 << 15 // channel is incoming 121 122 123 typedef enum { 124 L2CAP_CHANNEL_TYPE_CLASSIC, // Classic Basic or ERTM 125 L2CAP_CHANNEL_TYPE_CONNECTIONLESS, // Classic Connectionless 126 L2CAP_CHANNEL_TYPE_CHANNEL_CBM, // LE 127 L2CAP_CHANNEL_TYPE_FIXED_LE, // LE ATT + SM 128 L2CAP_CHANNEL_TYPE_FIXED_CLASSIC, // Classic SM 129 L2CAP_CHANNEL_TYPE_CHANNEL_ECBM // Classic + LE 130 } l2cap_channel_type_t; 131 132 133 /* 134 * @brief L2CAP Segmentation And Reassembly packet type in I-Frames 135 */ 136 typedef enum { 137 L2CAP_SEGMENTATION_AND_REASSEMBLY_UNSEGMENTED_L2CAP_SDU = 0, 138 L2CAP_SEGMENTATION_AND_REASSEMBLY_START_OF_L2CAP_SDU, 139 L2CAP_SEGMENTATION_AND_REASSEMBLY_END_OF_L2CAP_SDU, 140 L2CAP_SEGMENTATION_AND_REASSEMBLY_CONTINUATION_OF_L2CAP_SDU 141 } l2cap_segmentation_and_reassembly_t; 142 143 typedef struct { 144 l2cap_segmentation_and_reassembly_t sar; 145 uint16_t len; 146 uint8_t valid; 147 } l2cap_ertm_rx_packet_state_t; 148 149 typedef struct { 150 l2cap_segmentation_and_reassembly_t sar; 151 uint16_t len; 152 uint8_t tx_seq; 153 uint8_t retry_count; 154 uint8_t retransmission_requested; 155 } l2cap_ertm_tx_packet_state_t; 156 157 typedef struct { 158 // If not mandatory, the use of ERTM can be decided by the remote 159 uint8_t ertm_mandatory; 160 161 // Number of retransmissions that L2CAP is allowed to try before accepting that a packet and the channel is lost. 162 uint8_t max_transmit; 163 164 // time before retransmission of i-frame / Recommended : 2000 ms (ACL Flush timeout not used) 165 uint16_t retransmission_timeout_ms; 166 167 // time after withc s-frames are sent / Recommended: 12000 ms (ACL Flush timeout not used) 168 uint16_t monitor_timeout_ms; 169 170 // MTU for incoming SDUs 171 uint16_t local_mtu; 172 173 // Number of buffers for outgoing data 174 uint8_t num_tx_buffers; 175 176 // Number of packets that can be received out of order (-> our tx_window size) 177 uint8_t num_rx_buffers; 178 179 // Frame Check Sequence (FCS) Option 180 uint8_t fcs_option; 181 182 } l2cap_ertm_config_t; 183 184 // info regarding an actual channel 185 // note: l2cap_fixed_channel and l2cap_channel_t share commmon fields 186 187 typedef struct l2cap_fixed_channel { 188 // linked list - assert: first field 189 btstack_linked_item_t item; 190 191 // channel type 192 l2cap_channel_type_t channel_type; 193 194 // local cid, primary key for channel lookup 195 uint16_t local_cid; 196 197 // packet handler 198 btstack_packet_handler_t packet_handler; 199 200 // send request 201 uint8_t waiting_for_can_send_now; 202 203 // -- end of shared prefix 204 205 } l2cap_fixed_channel_t; 206 207 typedef struct { 208 // linked list - assert: first field 209 btstack_linked_item_t item; 210 211 // channel type 212 l2cap_channel_type_t channel_type; 213 214 // local cid, primary key for channel lookup 215 uint16_t local_cid; 216 217 // packet handler 218 btstack_packet_handler_t packet_handler; 219 220 // send request 221 uint8_t waiting_for_can_send_now; 222 223 // -- end of shared prefix 224 225 // timer 226 btstack_timer_source_t rtx; // also used for ertx 227 228 L2CAP_STATE state; 229 uint16_t state_var; 230 231 // info 232 hci_con_handle_t con_handle; 233 234 bd_addr_t address; 235 bd_addr_type_t address_type; 236 237 uint8_t remote_sig_id; // used by other side, needed for delayed response 238 uint8_t local_sig_id; // own signaling identifier 239 240 uint16_t remote_cid; 241 242 uint16_t local_mtu; 243 uint16_t remote_mtu; 244 245 uint16_t flush_timeout; // default 0xffff 246 247 uint16_t psm; 248 249 gap_security_level_t required_security_level; 250 251 uint16_t reason; // used in decline internal 252 253 uint8_t unknown_option; // used for ConfigResponse 254 255 // Credit-Based Flow-Control mode 256 257 // incoming SDU 258 uint8_t * receive_sdu_buffer; 259 uint16_t receive_sdu_len; 260 uint16_t receive_sdu_pos; 261 262 #ifdef ENABLE_L2CAP_ENHANCED_CREDIT_BASED_FLOW_CONTROL_MODE 263 uint8_t * renegotiate_sdu_buffer; 264 uint16_t renegotiate_mtu; 265 #endif 266 267 // outgoing SDU 268 const uint8_t * send_sdu_buffer; 269 uint16_t send_sdu_len; 270 uint16_t send_sdu_pos; 271 272 // max PDU size 273 uint16_t local_mps; 274 uint16_t remote_mps; 275 276 // credits for outgoing traffic 277 uint16_t credits_outgoing; 278 279 // number of packets remote will be granted 280 uint16_t new_credits_incoming; 281 282 // credits for incoming traffic 283 uint16_t credits_incoming; 284 285 // automatic credits incoming 286 bool automatic_credits; 287 288 #ifdef ENABLE_L2CAP_ENHANCED_CREDIT_BASED_FLOW_CONTROL_MODE 289 uint8_t cid_index; 290 uint8_t num_cids; 291 #endif 292 293 #ifdef ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE 294 295 // l2cap channel mode: basic or enhanced retransmission mode 296 l2cap_channel_mode_t mode; 297 298 // retransmission timer 299 btstack_timer_source_t retransmission_timer; 300 301 // monitor timer 302 btstack_timer_source_t monitor_timer; 303 304 // local/remote config options 305 uint16_t local_retransmission_timeout_ms; 306 uint16_t local_monitor_timeout_ms; 307 308 uint16_t remote_retransmission_timeout_ms; 309 uint16_t remote_monitor_timeout_ms; 310 311 uint8_t remote_tx_window_size; 312 313 uint8_t local_max_transmit; 314 uint8_t remote_max_transmit; 315 316 // if ertm is not mandatory, allow fallback to L2CAP Basic Mode - flag 317 uint8_t ertm_mandatory; 318 319 // Frame Check Sequence local (from ertm config) 320 uint8_t fcs_option; 321 322 // Frame Check Sequence was requested by either side 323 bool fcs_active; 324 325 // sender: max num of stored outgoing frames 326 uint8_t num_tx_buffers; 327 328 // sender: num stored outgoing frames 329 uint8_t num_stored_tx_frames; 330 331 // sender: number of unacknowledeged I-Frames - frames have been sent, but not acknowledged yet 332 uint8_t unacked_frames; 333 334 // sender: buffer index of oldest packet 335 uint8_t tx_read_index; 336 337 // sender: buffer index to store next tx packet 338 uint8_t tx_write_index; 339 340 // sender: buffer index of packet to send next 341 uint8_t tx_send_index; 342 343 // sender: next seq nr used for sending 344 uint8_t next_tx_seq; 345 346 // sender: selective retransmission requested 347 uint8_t srej_active; 348 349 350 // receiver: max num out-of-order packets // tx_window 351 uint8_t num_rx_buffers; 352 353 // receiver: buffer index of to store packet with delta = 1 354 uint8_t rx_store_index; 355 356 // receiver: value of tx_seq in next expected i-frame 357 uint8_t expected_tx_seq; 358 359 // receiver: request transmission with tx_seq = req_seq and ack up to and including req_seq 360 uint8_t req_seq; 361 362 // receiver: local busy condition 363 uint8_t local_busy; 364 365 // receiver: send RR frame with optional final flag set - flag 366 uint8_t send_supervisor_frame_receiver_ready; 367 368 // receiver: send RR frame with poll bit set 369 uint8_t send_supervisor_frame_receiver_ready_poll; 370 371 // receiver: send RNR frame - flag 372 uint8_t send_supervisor_frame_receiver_not_ready; 373 374 // receiver: send REJ frame - flag 375 uint8_t send_supervisor_frame_reject; 376 377 // receiver: send SREJ frame - flag 378 uint8_t send_supervisor_frame_selective_reject; 379 380 // set final bit after poll packet with poll bit was received 381 uint8_t set_final_bit_after_packet_with_poll_bit_set; 382 383 // receiver: meta data for out-of-order frames 384 l2cap_ertm_rx_packet_state_t * rx_packets_state; 385 386 // sender: retransmission state 387 l2cap_ertm_tx_packet_state_t * tx_packets_state; 388 389 // receiver: reassemly pos 390 uint16_t reassembly_pos; 391 392 // receiver: reassemly sdu length 393 uint16_t reassembly_sdu_length; 394 395 // receiver: eassembly buffer 396 uint8_t * reassembly_buffer; 397 398 // receiver: num_rx_buffers of size local_mps 399 uint8_t * rx_packets_data; 400 401 // sender: num_tx_buffers of size local_mps 402 uint8_t * tx_packets_data; 403 404 #endif 405 } l2cap_channel_t; 406 407 // info regarding potential connections 408 typedef struct { 409 // linked list - assert: first field 410 btstack_linked_item_t item; 411 412 // service id 413 uint16_t psm; 414 415 // max local mtu for basic mode, min remote mtu for enhanced credit-based flow-control mode 416 uint16_t mtu; 417 418 // internal connection 419 btstack_packet_handler_t packet_handler; 420 421 // required security level 422 gap_security_level_t required_security_level; 423 424 // requires authorization 425 bool requires_authorization; 426 427 } l2cap_service_t; 428 429 430 typedef struct l2cap_signaling_response { 431 hci_con_handle_t handle; 432 uint8_t sig_id; 433 uint8_t code; 434 uint16_t cid; // source cid for CONNECTION REQUEST 435 uint16_t data; // infoType for INFORMATION REQUEST, result for CONNECTION REQUEST and COMMAND UNKNOWN 436 } l2cap_signaling_response_t; 437 438 439 void l2cap_register_fixed_channel(btstack_packet_handler_t packet_handler, uint16_t channel_id); 440 bool l2cap_can_send_fixed_channel_packet_now(hci_con_handle_t con_handle, uint16_t channel_id); 441 void l2cap_request_can_send_fix_channel_now_event(hci_con_handle_t con_handle, uint16_t channel_id); 442 uint8_t l2cap_send_connectionless(hci_con_handle_t con_handle, uint16_t cid, uint8_t *data, uint16_t len); 443 uint8_t l2cap_send_prepared_connectionless(hci_con_handle_t con_handle, uint16_t cid, uint16_t len); 444 445 // PTS Testing 446 int l2cap_send_echo_request(hci_con_handle_t con_handle, uint8_t *data, uint16_t len); 447 void l2cap_require_security_level_2_for_outgoing_sdp(void); 448 449 // Used by RFCOMM - similar to l2cap_can-send_packet_now but does not check if outgoing buffer is reserved 450 bool l2cap_can_send_prepared_packet_now(uint16_t local_cid); 451 452 /* API_START */ 453 454 // 455 // PSM numbers from https://www.bluetooth.com/specifications/assigned-numbers/logical-link-control 456 // 457 #define PSM_SDP BLUETOOTH_PROTOCOL_SDP 458 #define PSM_RFCOMM BLUETOOTH_PROTOCOL_RFCOMM 459 #define PSM_BNEP BLUETOOTH_PROTOCOL_BNEP 460 // @TODO: scrape PSMs Bluetooth SIG site and put in bluetooth_psm.h or bluetooth_l2cap.h 461 #define PSM_HID_CONTROL 0x11 462 #define PSM_HID_INTERRUPT 0x13 463 #define PSM_ATT 0x1f 464 #define PSM_IPSP 0x23 465 466 /** 467 * @brief Set up L2CAP and register L2CAP with HCI layer. 468 */ 469 void l2cap_init(void); 470 471 /** 472 * @brief Add event packet handler for LE Connection Parameter Update events 473 */ 474 void l2cap_add_event_handler(btstack_packet_callback_registration_t * callback_handler); 475 476 /** 477 * @brief Remove event packet handler. 478 */ 479 void l2cap_remove_event_handler(btstack_packet_callback_registration_t * callback_handler); 480 481 /** 482 * @brief Get max MTU for Classic connections based on btstack configuration 483 */ 484 uint16_t l2cap_max_mtu(void); 485 486 /** 487 * @brief Get max MTU for LE connections based on btstack configuration 488 */ 489 uint16_t l2cap_max_le_mtu(void); 490 491 /** 492 * @brief Set the max MTU for LE connections, if not set l2cap_max_mtu() will be used. 493 */ 494 void l2cap_set_max_le_mtu(uint16_t max_mtu); 495 496 /** 497 * @brief Creates L2CAP channel to the PSM of a remote device with baseband address. A new baseband connection will be initiated if necessary. 498 * @param packet_handler 499 * @param address 500 * @param psm 501 * @param mtu 502 * @param local_cid 503 * @return status 504 */ 505 uint8_t l2cap_create_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, uint16_t mtu, uint16_t * out_local_cid); 506 507 /** 508 * @brief Disconnects L2CAP channel with given identifier. 509 * @param local_cid 510 * @return status ERROR_CODE_SUCCESS if successful or L2CAP_LOCAL_CID_DOES_NOT_EXIST 511 */ 512 uint8_t l2cap_disconnect(uint16_t local_cid); 513 514 /** 515 * @brief Queries the maximal transfer unit (MTU) for L2CAP channel with given identifier. 516 */ 517 uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid); 518 519 /** 520 * @brief Sends L2CAP data packet to the channel with given identifier. 521 * @note For channel in credit-based flow control mode, data needs to stay valid until .. event 522 * @param local_cid 523 * @param data to send 524 * @param len of data 525 * @return status 526 */ 527 uint8_t l2cap_send(uint16_t local_cid, const uint8_t *data, uint16_t len); 528 529 /** 530 * @brief Registers L2CAP service with given PSM and MTU, and assigns a packet handler. 531 * @param packet_handler 532 * @param psm 533 * @param mtu 534 * @param security_level 535 * @return status ERROR_CODE_SUCCESS if successful, otherwise L2CAP_SERVICE_ALREADY_REGISTERED or BTSTACK_MEMORY_ALLOC_FAILED 536 */ 537 uint8_t l2cap_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu, gap_security_level_t security_level); 538 539 /** 540 * @brief Unregisters L2CAP service with given PSM. 541 */ 542 uint8_t l2cap_unregister_service(uint16_t psm); 543 544 /** 545 * @brief Accepts incoming L2CAP connection. 546 */ 547 void l2cap_accept_connection(uint16_t local_cid); 548 549 /** 550 * @brief Deny incoming L2CAP connection. 551 */ 552 void l2cap_decline_connection(uint16_t local_cid); 553 554 /** 555 * @brief Check if outgoing buffer is available and that there's space on the Bluetooth module 556 * @return true if packet can be sent 557 */ 558 bool l2cap_can_send_packet_now(uint16_t local_cid); 559 560 /** 561 * @brief Request emission of L2CAP_EVENT_CAN_SEND_NOW as soon as possible 562 * @note L2CAP_EVENT_CAN_SEND_NOW might be emitted during call to this function 563 * so packet handler should be ready to handle it 564 * @param local_cid 565 * @return status 566 */ 567 uint8_t l2cap_request_can_send_now_event(uint16_t local_cid); 568 569 /** 570 * @brief Reserve outgoing buffer 571 * @note Only for L2CAP Basic Mode Channels 572 * @note Must only be called after a 'can send now' check or event 573 * @note Asserts if packet buffer is already reserved 574 */ 575 void l2cap_reserve_packet_buffer(void); 576 577 /** 578 * @brief Get outgoing buffer and prepare data. 579 * @note Only for L2CAP Basic Mode Channels 580 */ 581 uint8_t *l2cap_get_outgoing_buffer(void); 582 583 /** 584 * @brief Send L2CAP packet prepared in outgoing buffer to channel 585 * @note Only for L2CAP Basic Mode Channels 586 */ 587 uint8_t l2cap_send_prepared(uint16_t local_cid, uint16_t len); 588 589 /** 590 * @brief Release outgoing buffer (only needed if l2cap_send_prepared is not called) 591 * @note Only for L2CAP Basic Mode Channels 592 */ 593 void l2cap_release_packet_buffer(void); 594 595 // 596 // Connection-Oriented Channels in Enhanced Retransmission Mode - ERTM 597 // 598 599 /** 600 * @brief Creates L2CAP channel to the PSM of a remote device with baseband address using Enhanced Retransmission Mode. 601 * A new baseband connection will be initiated if necessary. 602 * @param packet_handler 603 * @param address 604 * @param psm 605 * @param ertm_config 606 * @param buffer to store reassembled rx packet, out-of-order packets and unacknowledged outgoing packets with their tretransmission timers 607 * @param size of buffer 608 * @param local_cid 609 * @return status 610 */ 611 uint8_t l2cap_ertm_create_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, 612 l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size, uint16_t * out_local_cid); 613 614 /** 615 * @brief Accepts incoming L2CAP connection for Enhanced Retransmission Mode 616 * @param local_cid 617 * @param ertm_config 618 * @param buffer to store reassembled rx packet, out-of-order packets and unacknowledged outgoing packets with their tretransmission timers 619 * @param size of buffer 620 * @return status 621 */ 622 uint8_t l2cap_ertm_accept_connection(uint16_t local_cid, l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size); 623 624 /** 625 * @brief Deny incoming incoming L2CAP connection for Enhanced Retransmission Mode 626 * @param local_cid 627 * @return status 628 */ 629 uint8_t l2cap_ertm_decline_connection(uint16_t local_cid); 630 631 /** 632 * @brief ERTM Set channel as busy. 633 * @note Can be cleared by l2cap_ertm_set_ready 634 * @param local_cid 635 * @return status 636 */ 637 uint8_t l2cap_ertm_set_busy(uint16_t local_cid); 638 639 /** 640 * @brief ERTM Set channel as ready 641 * @note Used after l2cap_ertm_set_busy 642 * @param local_cid 643 * @return status 644 */ 645 uint8_t l2cap_ertm_set_ready(uint16_t local_cid); 646 647 648 // 649 // L2CAP Connection-Oriented Channels in LE Credit-Based Flow-Control Mode - CBM 650 // 651 652 /** 653 * @brief Register L2CAP service in LE Credit-Based Flow-Control Mode 654 * @note MTU and initial credits are specified in l2cap_cbm_accept_connection(..) call 655 * @param packet_handler 656 * @param psm 657 * @param security_level 658 */ 659 uint8_t l2cap_cbm_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, gap_security_level_t security_level); 660 661 /** 662 * @brief Unregister L2CAP service in LE Credit-Based Flow-Control Mode 663 * @param psm 664 */ 665 666 uint8_t l2cap_cbm_unregister_service(uint16_t psm); 667 668 /* 669 * @brief Accept incoming connection LE Credit-Based Flow-Control Mode 670 * @param local_cid L2CAP Channel Identifier 671 * @param receive_buffer buffer used for reassembly of L2CAP LE Information Frames into service data unit (SDU) with given MTU 672 * @param receive_buffer_size buffer size equals MTU 673 * @param initial_credits Number of initial credits provided to peer or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 674 */ 675 676 uint8_t l2cap_cbm_accept_connection(uint16_t local_cid, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits); 677 678 /** 679 * @brief Deecline connection in LE Credit-Based Flow-Control Mode 680 * @param local_cid L2CAP Channel Identifier 681 * @param result result, see L2CAP_CBM_CONNECTION_RESULT_SUCCESS in bluetooth.h 682 */ 683 684 uint8_t l2cap_cbm_decline_connection(uint16_t local_cid, uint16_t result); 685 686 /** 687 * @brief Create outgoing channel in LE Credit-Based Flow-Control Mode 688 * @param packet_handler Packet handler for this connection 689 * @param con_handle HCI Connection Handle, LE transport 690 * @param psm Service PSM to connect to 691 * @param receive_buffer buffer used for reassembly of L2CAP LE Information Frames into service data unit (SDU) with given MTU 692 * @param receive_buffer_size buffer size equals MTU 693 * @param initial_credits Number of initial credits provided to peer or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 694 * @param security_level Minimum required security level 695 * @param out_local_cid L2CAP LE Channel Identifier is stored here 696 */ 697 uint8_t l2cap_cbm_create_channel(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle, 698 uint16_t psm, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits, gap_security_level_t security_level, 699 uint16_t * out_local_cid); 700 701 /** 702 * @brief Provide credits for channel in LE Credit-Based Flow-Control Mode 703 * @param local_cid L2CAP Channel Identifier 704 * @param credits Number additional credits for peer 705 */ 706 uint8_t l2cap_cbm_provide_credits(uint16_t local_cid, uint16_t credits); 707 708 /** 709 * @brief Returns the number of credits provided by peer 710 * @param local_cid 711 * @return number of credits 712 */ 713 uint16_t l2cap_cbm_available_credits(uint16_t local_cid); 714 715 // 716 // L2CAP Connection-Oriented Channels in Enhanced Credit-Based Flow-Control Mode - ECBM 717 // 718 719 /** 720 * @brief Register L2CAP service in Enhanced Credit-Based Flow-Control Mode 721 * @note MTU and initial credits are specified in l2cap_enhanced_accept_connection(..) call 722 * @param packet_handler 723 * @param psm 724 * @param min_remote_mtu 725 * @param security_level 726 * @oaram authorization_required 727 * @return status 728 */ 729 uint8_t l2cap_ecbm_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t min_remote_mtu, 730 gap_security_level_t security_level, bool authorization_required); 731 732 /** 733 * @brief Unregister L2CAP service in Enhanced Credit-Based Flow-Control Mode 734 * @param psm 735 * @return status 736 */ 737 738 uint8_t l2cap_ecbm_unregister_service(uint16_t psm); 739 740 /** 741 * @brief Set Minimal MPS for channel in Enhanced Credit-Based Flow-Control Mode 742 * @param mps_min 743 */ 744 void l2cap_ecbm_mps_set_min(uint16_t mps_min); 745 746 /** 747 * @brief Set Minimal MPS for channel in Enhanced Credit-Based Flow-Control Mode 748 * @param mps_max 749 */ 750 void l2cap_ecbm_mps_set_max(uint16_t mps_max); 751 752 /** 753 * @brief Create outgoing channel in Enhanced Credit-Based Flow-Control Mode 754 * @note receive_buffer points to an array of receive buffers with num_channels elements 755 * @note out_local_cid points to an array where CID is stored with num_channel elements 756 * @param packet_handler Packet handler for this connection 757 * @param con_handle HCI Connection Handle 758 * @param security_level Minimum required security level 759 * @param psm Service PSM to connect to 760 * @param num_channels number of channels to create 761 * @param initial_credits Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 762 * @param receive_buffer_size buffer size equals MTU 763 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 764 * @param out_local_cids Array of L2CAP Channel Identifiers is stored here on success 765 * @return status 766 */ 767 uint8_t l2cap_ecbm_create_channels(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle, 768 gap_security_level_t security_level, 769 uint16_t psm, uint8_t num_channels, uint16_t initial_credits, uint16_t receive_buffer_size, 770 uint8_t ** receive_buffers, uint16_t * out_local_cids); 771 772 /** 773 * @brief Accept incoming connection Enhanced Credit-Based Flow-Control Mode 774 * @param local_cid from L2CAP_EVENT_INCOMING_DATA_CONNECTION 775 * @param num_channels 776 * @param initial_credits Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 777 * @param receive_buffer_size 778 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 779 * @param out_local_cids Array of L2CAP Channel Identifiers is stored here on success 780 * @return status 781 */ 782 uint8_t l2cap_ecbm_accept_channels(uint16_t local_cid, uint8_t num_channels, uint16_t initial_credits, 783 uint16_t receive_buffer_size, uint8_t ** receive_buffers, uint16_t * out_local_cids); 784 /** 785 * @brief Decline connection in Enhanced Credit-Based Flow-Control Mode 786 * @param local_cid from L2CAP_EVENT_INCOMING_DATA_CONNECTION 787 * @param result See L2CAP_ECBM_CONNECTION_RESULT_ALL_SUCCESS in bluetooth.h 788 * @return status 789 */ 790 uint8_t l2cap_ecbm_decline_channels(uint16_t local_cid, uint16_t result); 791 792 /** 793 * @brief Provide credits for channel in Enhanced Credit-Based Flow-Control Mode 794 * @param local_cid L2CAP Channel Identifier 795 * @param credits Number additional credits for peer 796 * @return status 797 */ 798 uint8_t l2cap_ecbm_provide_credits(uint16_t local_cid, uint16_t credits); 799 800 /** 801 * @brief Request emission of L2CAP_EVENT_ECBM_CAN_SEND_NOW as soon as possible 802 * @note L2CAP_EVENT_ECBM_CAN_SEND_NOW might be emitted during call to this function 803 * so packet handler should be ready to handle it 804 * @param local_cid L2CAP Channel Identifier 805 * @return status 806 */ 807 uint8_t l2cap_ecbm_request_can_send_now_event(uint16_t local_cid); 808 809 /** 810 * @brief Reconfigure MPS/MTU of local channels 811 * @param num_cids 812 * @param local_cids array of local_cids to reconfigure 813 * @param receive_buffer_size buffer size equals MTU 814 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 815 * @return status 816 */ 817 uint8_t l2cap_ecbm_reconfigure_channels(uint8_t num_cids, uint16_t * local_cids, int16_t receive_buffer_size, uint8_t ** receive_buffers); 818 819 /** 820 * @brief Trigger pending connection responses after pairing completed 821 * @note Must be called after receiving an SM_PAIRING_COMPLETE event, will be removed eventually 822 * @param con_handle 823 */ 824 void l2cap_ecbm_trigger_pending_connection_responses(hci_con_handle_t con_handle); 825 826 /** 827 * @brief Returns the number of outgoing credits provided by peer 828 * @param local_cid 829 * @return number of credits 830 */ 831 uint16_t l2cap_ecbm_available_credits(uint16_t local_cid); 832 833 /** 834 * @brief De-Init L2CAP 835 */ 836 void l2cap_deinit(void); 837 838 /* API_END */ 839 840 841 // @deprecated - please use l2cap_ertm_create_channel 842 uint8_t l2cap_create_ertm_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size, uint16_t * out_local_cid); 843 844 // @deprecated - please use l2cap_ertm_accept_connection 845 uint8_t l2cap_accept_ertm_connection(uint16_t local_cid, l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size); 846 847 // @deprecated - please use l2cap_cbm_register_service 848 uint8_t l2cap_le_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, gap_security_level_t security_level); 849 850 // @deprecated - please use l2cap_cbm_unregister_service 851 uint8_t l2cap_le_unregister_service(uint16_t psm); 852 853 // @deprecated - please use l2cap_cbm_accept_connection 854 uint8_t l2cap_le_accept_connection(uint16_t local_cid, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits); 855 856 // @deprecated - please use l2cap_cbm_decline_connection 857 uint8_t l2cap_le_decline_connection(uint16_t local_cid); 858 859 // @deprecated - please use l2cap_cbm_create_channel 860 uint8_t l2cap_le_create_channel(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle, 861 uint16_t psm, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits, gap_security_level_t security_level, 862 uint16_t * out_local_cid); 863 864 // @deprecated - please use l2cap_cbm_provide_credits 865 uint8_t l2cap_le_provide_credits(uint16_t local_cid, uint16_t credits); 866 867 // @deprecated - please use l2cap_can_send_now 868 bool l2cap_le_can_send_now(uint16_t local_cid); 869 870 // @deprecated - please use l2cap_request_can_send_now_event 871 uint8_t l2cap_le_request_can_send_now_event(uint16_t local_cid); 872 873 // @deprecated - please use l2cap_send 874 uint8_t l2cap_le_send_data(uint16_t local_cid, const uint8_t * data, uint16_t size); 875 876 // @deprecated - please use l2cap_disconnect 877 uint8_t l2cap_le_disconnect(uint16_t local_cid); 878 879 880 #if defined __cplusplus 881 } 882 #endif 883 884 #endif // L2CAP_H 885