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_LE_DATA_CHANNEL, // LE 127 L2CAP_CHANNEL_TYPE_FIXED, // LE ATT + SM, Classic SM 128 L2CAP_CHANNEL_TYPE_ENHANCED_DATA_CHANNEL // Classic + LE 129 } l2cap_channel_type_t; 130 131 132 /* 133 * @brief L2CAP Segmentation And Reassembly packet type in I-Frames 134 */ 135 typedef enum { 136 L2CAP_SEGMENTATION_AND_REASSEMBLY_UNSEGMENTED_L2CAP_SDU = 0, 137 L2CAP_SEGMENTATION_AND_REASSEMBLY_START_OF_L2CAP_SDU, 138 L2CAP_SEGMENTATION_AND_REASSEMBLY_END_OF_L2CAP_SDU, 139 L2CAP_SEGMENTATION_AND_REASSEMBLY_CONTINUATION_OF_L2CAP_SDU 140 } l2cap_segmentation_and_reassembly_t; 141 142 typedef struct { 143 l2cap_segmentation_and_reassembly_t sar; 144 uint16_t len; 145 uint8_t valid; 146 } l2cap_ertm_rx_packet_state_t; 147 148 typedef struct { 149 l2cap_segmentation_and_reassembly_t sar; 150 uint16_t len; 151 uint8_t tx_seq; 152 uint8_t retry_count; 153 uint8_t retransmission_requested; 154 } l2cap_ertm_tx_packet_state_t; 155 156 typedef struct { 157 // If not mandatory, the use of ERTM can be decided by the remote 158 uint8_t ertm_mandatory; 159 160 // Number of retransmissions that L2CAP is allowed to try before accepting that a packet and the channel is lost. 161 uint8_t max_transmit; 162 163 // time before retransmission of i-frame / Recommended : 2000 ms (ACL Flush timeout not used) 164 uint16_t retransmission_timeout_ms; 165 166 // time after withc s-frames are sent / Recommended: 12000 ms (ACL Flush timeout not used) 167 uint16_t monitor_timeout_ms; 168 169 // MTU for incoming SDUs 170 uint16_t local_mtu; 171 172 // Number of buffers for outgoing data 173 uint8_t num_tx_buffers; 174 175 // Number of packets that can be received out of order (-> our tx_window size) 176 uint8_t num_rx_buffers; 177 178 // Frame Check Sequence (FCS) Option 179 uint8_t fcs_option; 180 181 } l2cap_ertm_config_t; 182 183 // info regarding an actual channel 184 // note: l2cap_fixed_channel and l2cap_channel_t share commmon fields 185 186 typedef struct l2cap_fixed_channel { 187 // linked list - assert: first field 188 btstack_linked_item_t item; 189 190 // channel type 191 l2cap_channel_type_t channel_type; 192 193 // local cid, primary key for channel lookup 194 uint16_t local_cid; 195 196 // packet handler 197 btstack_packet_handler_t packet_handler; 198 199 // send request 200 uint8_t waiting_for_can_send_now; 201 202 // -- end of shared prefix 203 204 } l2cap_fixed_channel_t; 205 206 typedef struct { 207 // linked list - assert: first field 208 btstack_linked_item_t item; 209 210 // channel type 211 l2cap_channel_type_t channel_type; 212 213 // local cid, primary key for channel lookup 214 uint16_t local_cid; 215 216 // packet handler 217 btstack_packet_handler_t packet_handler; 218 219 // send request 220 uint8_t waiting_for_can_send_now; 221 222 // -- end of shared prefix 223 224 // timer 225 btstack_timer_source_t rtx; // also used for ertx 226 227 L2CAP_STATE state; 228 uint16_t state_var; 229 230 // info 231 hci_con_handle_t con_handle; 232 233 bd_addr_t address; 234 bd_addr_type_t address_type; 235 236 uint8_t remote_sig_id; // used by other side, needed for delayed response 237 uint8_t local_sig_id; // own signaling identifier 238 239 uint16_t remote_cid; 240 241 uint16_t local_mtu; 242 uint16_t remote_mtu; 243 244 uint16_t flush_timeout; // default 0xffff 245 246 uint16_t psm; 247 248 gap_security_level_t required_security_level; 249 250 uint8_t reason; // used in decline internal 251 252 uint8_t unknown_option; // used for ConfigResponse 253 254 // LE Data Channels 255 256 // incoming SDU 257 uint8_t * receive_sdu_buffer; 258 uint16_t receive_sdu_len; 259 uint16_t receive_sdu_pos; 260 261 #ifdef ENABLE_L2CAP_ENHANCED_DATA_CHANNELS 262 uint8_t * renegotiate_sdu_buffer; 263 uint16_t renegotiate_mtu; 264 #endif 265 266 // outgoing SDU 267 const uint8_t * send_sdu_buffer; 268 uint16_t send_sdu_len; 269 uint16_t send_sdu_pos; 270 271 // max PDU size 272 uint16_t remote_mps; 273 274 // credits for outgoing traffic 275 uint16_t credits_outgoing; 276 277 // number of packets remote will be granted 278 uint16_t new_credits_incoming; 279 280 // credits for incoming traffic 281 uint16_t credits_incoming; 282 283 // automatic credits incoming 284 uint16_t automatic_credits; 285 286 #ifdef ENABLE_L2CAP_ENHANCED_DATA_CHANNELS 287 uint8_t cid_index; 288 uint8_t num_cids; 289 #endif 290 291 #ifdef ENABLE_L2CAP_ENHANCED_RETRANSMISSION_MODE 292 293 // l2cap channel mode: basic or enhanced retransmission mode 294 l2cap_channel_mode_t mode; 295 296 // local mps = size of rx/tx buffers 297 uint16_t local_mps; 298 299 // retransmission timer 300 btstack_timer_source_t retransmission_timer; 301 302 // monitor timer 303 btstack_timer_source_t monitor_timer; 304 305 // local/remote config options 306 uint16_t local_retransmission_timeout_ms; 307 uint16_t local_monitor_timeout_ms; 308 309 uint16_t remote_retransmission_timeout_ms; 310 uint16_t remote_monitor_timeout_ms; 311 312 uint8_t remote_tx_window_size; 313 314 uint8_t local_max_transmit; 315 uint8_t remote_max_transmit; 316 317 // if ertm is not mandatory, allow fallback to L2CAP Basic Mode - flag 318 uint8_t ertm_mandatory; 319 320 // Frame Chech Sequence (crc16) is present in both directions 321 uint8_t fcs_option; 322 323 // sender: max num of stored outgoing frames 324 uint8_t num_tx_buffers; 325 326 // sender: num stored outgoing frames 327 uint8_t num_stored_tx_frames; 328 329 // sender: number of unacknowledeged I-Frames - frames have been sent, but not acknowledged yet 330 uint8_t unacked_frames; 331 332 // sender: buffer index of oldest packet 333 uint8_t tx_read_index; 334 335 // sender: buffer index to store next tx packet 336 uint8_t tx_write_index; 337 338 // sender: buffer index of packet to send next 339 uint8_t tx_send_index; 340 341 // sender: next seq nr used for sending 342 uint8_t next_tx_seq; 343 344 // sender: selective retransmission requested 345 uint8_t srej_active; 346 347 348 // receiver: max num out-of-order packets // tx_window 349 uint8_t num_rx_buffers; 350 351 // receiver: buffer index of to store packet with delta = 1 352 uint8_t rx_store_index; 353 354 // receiver: value of tx_seq in next expected i-frame 355 uint8_t expected_tx_seq; 356 357 // receiver: request transmission with tx_seq = req_seq and ack up to and including req_seq 358 uint8_t req_seq; 359 360 // receiver: local busy condition 361 uint8_t local_busy; 362 363 // receiver: send RR frame with optional final flag set - flag 364 uint8_t send_supervisor_frame_receiver_ready; 365 366 // receiver: send RR frame with poll bit set 367 uint8_t send_supervisor_frame_receiver_ready_poll; 368 369 // receiver: send RNR frame - flag 370 uint8_t send_supervisor_frame_receiver_not_ready; 371 372 // receiver: send REJ frame - flag 373 uint8_t send_supervisor_frame_reject; 374 375 // receiver: send SREJ frame - flag 376 uint8_t send_supervisor_frame_selective_reject; 377 378 // set final bit after poll packet with poll bit was received 379 uint8_t set_final_bit_after_packet_with_poll_bit_set; 380 381 // receiver: meta data for out-of-order frames 382 l2cap_ertm_rx_packet_state_t * rx_packets_state; 383 384 // sender: retransmission state 385 l2cap_ertm_tx_packet_state_t * tx_packets_state; 386 387 // receiver: reassemly pos 388 uint16_t reassembly_pos; 389 390 // receiver: reassemly sdu length 391 uint16_t reassembly_sdu_length; 392 393 // receiver: eassembly buffer 394 uint8_t * reassembly_buffer; 395 396 // receiver: num_rx_buffers of size local_mps 397 uint8_t * rx_packets_data; 398 399 // sender: num_tx_buffers of size local_mps 400 uint8_t * tx_packets_data; 401 402 #endif 403 } l2cap_channel_t; 404 405 // info regarding potential connections 406 typedef struct { 407 // linked list - assert: first field 408 btstack_linked_item_t item; 409 410 // service id 411 uint16_t psm; 412 413 // max local mtu for basic mode, min remote mtu for enhanced data channels 414 uint16_t mtu; 415 416 // internal connection 417 btstack_packet_handler_t packet_handler; 418 419 // required security level 420 gap_security_level_t required_security_level; 421 422 } l2cap_service_t; 423 424 425 typedef struct l2cap_signaling_response { 426 hci_con_handle_t handle; 427 uint8_t sig_id; 428 uint8_t code; 429 uint16_t cid; // source cid for CONNECTION REQUEST 430 uint16_t data; // infoType for INFORMATION REQUEST, result for CONNECTION REQUEST and COMMAND UNKNOWN 431 } l2cap_signaling_response_t; 432 433 434 void l2cap_register_fixed_channel(btstack_packet_handler_t packet_handler, uint16_t channel_id); 435 bool l2cap_can_send_fixed_channel_packet_now(hci_con_handle_t con_handle, uint16_t channel_id); 436 void l2cap_request_can_send_fix_channel_now_event(hci_con_handle_t con_handle, uint16_t channel_id); 437 uint8_t l2cap_send_connectionless(hci_con_handle_t con_handle, uint16_t cid, uint8_t *data, uint16_t len); 438 uint8_t l2cap_send_prepared_connectionless(hci_con_handle_t con_handle, uint16_t cid, uint16_t len); 439 440 // PTS Testing 441 int l2cap_send_echo_request(hci_con_handle_t con_handle, uint8_t *data, uint16_t len); 442 void l2cap_require_security_level_2_for_outgoing_sdp(void); 443 444 // Used by RFCOMM - similar to l2cap_can-send_packet_now but does not check if outgoing buffer is reserved 445 bool l2cap_can_send_prepared_packet_now(uint16_t local_cid); 446 447 /* API_START */ 448 449 // 450 // PSM numbers from https://www.bluetooth.com/specifications/assigned-numbers/logical-link-control 451 // 452 #define PSM_SDP BLUETOOTH_PROTOCOL_SDP 453 #define PSM_RFCOMM BLUETOOTH_PROTOCOL_RFCOMM 454 #define PSM_BNEP BLUETOOTH_PROTOCOL_BNEP 455 // @TODO: scrape PSMs Bluetooth SIG site and put in bluetooth_psm.h or bluetooth_l2cap.h 456 #define PSM_HID_CONTROL 0x11 457 #define PSM_HID_INTERRUPT 0x13 458 #define PSM_ATT 0x1f 459 #define PSM_IPSP 0x23 460 461 /** 462 * @brief Set up L2CAP and register L2CAP with HCI layer. 463 */ 464 void l2cap_init(void); 465 466 /** 467 * @brief Add event packet handler for LE Connection Parameter Update events 468 */ 469 void l2cap_add_event_handler(btstack_packet_callback_registration_t * callback_handler); 470 471 /** 472 * @brief Remove event packet handler. 473 */ 474 void l2cap_remove_event_handler(btstack_packet_callback_registration_t * callback_handler); 475 476 /** 477 * @brief Get max MTU for Classic connections based on btstack configuration 478 */ 479 uint16_t l2cap_max_mtu(void); 480 481 /** 482 * @brief Get max MTU for LE connections based on btstack configuration 483 */ 484 uint16_t l2cap_max_le_mtu(void); 485 486 /** 487 * @brief Set the max MTU for LE connections, if not set l2cap_max_mtu() will be used. 488 */ 489 void l2cap_set_max_le_mtu(uint16_t max_mtu); 490 491 /** 492 * @brief Creates L2CAP channel to the PSM of a remote device with baseband address. A new baseband connection will be initiated if necessary. 493 * @param packet_handler 494 * @param address 495 * @param psm 496 * @param mtu 497 * @param local_cid 498 * @return status 499 */ 500 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); 501 502 /** 503 * @brief Creates L2CAP channel to the PSM of a remote device with baseband address using Enhanced Retransmission Mode. 504 * A new baseband connection will be initiated if necessary. 505 * @param packet_handler 506 * @param address 507 * @param psm 508 * @param ertm_config 509 * @param buffer to store reassembled rx packet, out-of-order packets and unacknowledged outgoing packets with their tretransmission timers 510 * @param size of buffer 511 * @param local_cid 512 * @return status 513 */ 514 uint8_t l2cap_create_ertm_channel(btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, 515 l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size, uint16_t * out_local_cid); 516 517 /** 518 * @brief Disconnects L2CAP channel with given identifier. 519 */ 520 void l2cap_disconnect(uint16_t local_cid, uint8_t reason); 521 522 /** 523 * @brief Queries the maximal transfer unit (MTU) for L2CAP channel with given identifier. 524 */ 525 uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid); 526 527 /** 528 * @brief Sends L2CAP data packet to the channel with given identifier. 529 */ 530 uint8_t l2cap_send(uint16_t local_cid, uint8_t *data, uint16_t len); 531 532 /** 533 * @brief Registers L2CAP service with given PSM and MTU, and assigns a packet handler. 534 * @param packet_handler 535 * @param psm 536 * @param mtu 537 * @param security_level 538 * @return status ERROR_CODE_SUCCESS if successful, otherwise L2CAP_SERVICE_ALREADY_REGISTERED or BTSTACK_MEMORY_ALLOC_FAILED 539 */ 540 uint8_t l2cap_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu, gap_security_level_t security_level); 541 542 /** 543 * @brief Unregisters L2CAP service with given PSM. 544 */ 545 uint8_t l2cap_unregister_service(uint16_t psm); 546 547 /** 548 * @brief Accepts incoming L2CAP connection. 549 */ 550 void l2cap_accept_connection(uint16_t local_cid); 551 552 /** 553 * @brief Accepts incoming L2CAP connection for Enhanced Retransmission Mode 554 * @param local_cid 555 * @param ertm_config 556 * @param buffer to store reassembled rx packet, out-of-order packets and unacknowledged outgoing packets with their tretransmission timers 557 * @param size of buffer 558 * @return status 559 */ 560 uint8_t l2cap_accept_ertm_connection(uint16_t local_cid, l2cap_ertm_config_t * ertm_contig, uint8_t * buffer, uint32_t size); 561 562 /** 563 * @brief Deny incoming L2CAP connection. 564 */ 565 void l2cap_decline_connection(uint16_t local_cid); 566 567 /** 568 * @brief Check if outgoing buffer is available and that there's space on the Bluetooth module 569 * @return true if packet can be sent 570 */ 571 bool l2cap_can_send_packet_now(uint16_t local_cid); 572 573 /** 574 * @brief Request emission of L2CAP_EVENT_CAN_SEND_NOW as soon as possible 575 * @note L2CAP_EVENT_CAN_SEND_NOW might be emitted during call to this function 576 * so packet handler should be ready to handle it 577 * @param local_cid 578 */ 579 void l2cap_request_can_send_now_event(uint16_t local_cid); 580 581 /** 582 * @brief Reserve outgoing buffer 583 * @note Only for L2CAP Basic Mode Channels 584 * @return true on success 585 */ 586 bool l2cap_reserve_packet_buffer(void); 587 588 /** 589 * @brief Get outgoing buffer and prepare data. 590 * @note Only for L2CAP Basic Mode Channels 591 */ 592 uint8_t *l2cap_get_outgoing_buffer(void); 593 594 /** 595 * @brief Send L2CAP packet prepared in outgoing buffer to channel 596 * @note Only for L2CAP Basic Mode Channels 597 */ 598 uint8_t l2cap_send_prepared(uint16_t local_cid, uint16_t len); 599 600 /** 601 * @brief Release outgoing buffer (only needed if l2cap_send_prepared is not called) 602 * @note Only for L2CAP Basic Mode Channels 603 */ 604 void l2cap_release_packet_buffer(void); 605 606 607 // 608 // LE Connection Oriented Channels feature with the LE Credit Based Flow Control Mode == LE Data Channel 609 // 610 611 612 /** 613 * @brief Register L2CAP LE Data Channel service 614 * @note MTU and initial credits are specified in l2cap_le_accept_connection(..) call 615 * @param packet_handler 616 * @param psm 617 * @param security_level 618 */ 619 uint8_t l2cap_le_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, gap_security_level_t security_level); 620 621 /** 622 * @brief Unregister L2CAP LE Data Channel service 623 * @param psm 624 */ 625 626 uint8_t l2cap_le_unregister_service(uint16_t psm); 627 628 /* 629 * @brief Accept incoming LE Data Channel connection 630 * @param local_cid L2CAP LE Data Channel Identifier 631 * @param receive_buffer buffer used for reassembly of L2CAP LE Information Frames into service data unit (SDU) with given MTU 632 * @param receive_buffer_size buffer size equals MTU 633 * @param initial_credits Number of initial credits provided to peer or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 634 */ 635 636 uint8_t l2cap_le_accept_connection(uint16_t local_cid, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits); 637 638 /** 639 * @brief Deny incoming LE Data Channel connection due to resource constraints 640 * @param local_cid L2CAP LE Data Channel Identifier 641 */ 642 643 uint8_t l2cap_le_decline_connection(uint16_t local_cid); 644 645 /** 646 * @brief Create LE Data Channel 647 * @param packet_handler Packet handler for this connection 648 * @param con_handle ACL-LE HCI Connction Handle 649 * @param psm Service PSM to connect to 650 * @param receive_buffer buffer used for reassembly of L2CAP LE Information Frames into service data unit (SDU) with given MTU 651 * @param receive_buffer_size buffer size equals MTU 652 * @param initial_credits Number of initial credits provided to peer or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 653 * @param security_level Minimum required security level 654 * @param out_local_cid L2CAP LE Channel Identifier is stored here 655 */ 656 uint8_t l2cap_le_create_channel(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle, 657 uint16_t psm, uint8_t * receive_sdu_buffer, uint16_t mtu, uint16_t initial_credits, gap_security_level_t security_level, 658 uint16_t * out_local_cid); 659 660 /** 661 * @brief Provide credtis for LE Data Channel 662 * @param local_cid L2CAP LE Data Channel Identifier 663 * @param credits Number additional credits for peer 664 */ 665 uint8_t l2cap_le_provide_credits(uint16_t local_cid, uint16_t credits); 666 667 /** 668 * @brief Check if packet can be scheduled for transmission 669 * @param local_cid L2CAP LE Data Channel Identifier 670 * @return true if packet can be sent on local_cid 671 */ 672 bool l2cap_le_can_send_now(uint16_t local_cid); 673 674 /** 675 * @brief Request emission of L2CAP_EVENT_LE_CAN_SEND_NOW as soon as possible 676 * @note L2CAP_EVENT_CAN_SEND_NOW might be emitted during call to this function 677 * so packet handler should be ready to handle it 678 * @param local_cid L2CAP LE Data Channel Identifier 679 */ 680 uint8_t l2cap_le_request_can_send_now_event(uint16_t local_cid); 681 682 /** 683 * @brief Send data via LE Data Channel 684 * @note Since data larger then the maximum PDU needs to be segmented into multiple PDUs, data needs to stay valid until ... event 685 * @param local_cid L2CAP LE Data Channel Identifier 686 * @param data data to send 687 * @param size data size 688 */ 689 uint8_t l2cap_le_send_data(uint16_t local_cid, uint8_t * data, uint16_t size); 690 691 /** 692 * @brief Disconnect from LE Data Channel 693 * @param local_cid L2CAP LE Data Channel Identifier 694 */ 695 uint8_t l2cap_le_disconnect(uint16_t local_cid); 696 697 // 698 // L2CAP Connection Oriented Channels feature with the Enhanced Credit Based Flow Control Mode == L2CAP Enhanced Data Channel 699 // 700 701 /** 702 * @brief Register L2CAP Enhanced Data Channel service 703 * @note MTU and initial credits are specified in l2cap_enhanced_accept_connection(..) call 704 * @param packet_handler 705 * @param psm 706 * @param min_remote_mtu 707 * @param security_level 708 * @return status 709 */ 710 uint8_t l2cap_enhanced_register_service(btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t min_remote_mtu, gap_security_level_t security_level); 711 712 /** 713 * @brief Unregister L2CAP Enhanced Data Channel service 714 * @param psm 715 * @return status 716 */ 717 718 uint8_t l2cap_enhanced_unregister_service(uint16_t psm); 719 720 /** 721 * @brief Set Minimal MPS for Enhanced Data Channels 722 * @param mps_min 723 */ 724 void l2cap_enhanced_mps_set_min(uint16_t mps_min); 725 726 /** 727 * @brief Set Minimal MPS for Enhanced Data Channels 728 * @param mps_max 729 */ 730 void l2cap_enhanced_mps_set_max(uint16_t mps_max); 731 732 /** 733 * @brief Create Enhanced Data Channel 734 * @note receive_buffer points to an array of receive buffers with num_channels elements 735 * @note out_local_cid points to an array where CID is stored with num_channel elements 736 * @param packet_handler Packet handler for this connection 737 * @param con_handle ACL-LE HCI Connction Handle 738 * @param security_level Minimum required security level 739 * @param psm Service PSM to connect to 740 * @param num_channels number of channels to create 741 * @param initial_credits Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 742 * @param receive_buffer_size buffer size equals MTU 743 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 744 * @param out_local_cids Array of L2CAP Channel Identifiers is stored here on success 745 * @return status 746 */ 747 uint8_t l2cap_enhanced_create_channels(btstack_packet_handler_t packet_handler, hci_con_handle_t con_handle, 748 gap_security_level_t security_level, 749 uint16_t psm, uint8_t num_channels, uint16_t initial_credits, uint16_t receive_buffer_size, 750 uint8_t ** receive_buffers, uint16_t * out_local_cids); 751 752 /** 753 * @brief Accept incoming Enhanced Data Channel 754 * @param local_cid from L2CAP_EVENT_INCOMING_DATA_CONNECTION 755 * @param num_channels 756 * @param initial_credits Number of initial credits provided to peer per channel or L2CAP_LE_AUTOMATIC_CREDITS to enable automatic credits 757 * @param receive_buffer_size 758 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 759 * @param out_local_cids Array of L2CAP Channel Identifiers is stored here on success 760 * @return status 761 */ 762 uint8_t l2cap_enhanced_accept_data_channels(uint16_t local_cid, uint8_t num_channels, uint16_t initial_credits, 763 uint16_t receive_buffer_size, uint8_t ** receive_buffers, uint16_t * out_local_cids); 764 /** 765 * @brief Accept/Reject incoming Enhanced Data Channel 766 * @param local_cid from L2CAP_EVENT_INCOMING_DATA_CONNECTION 767 * @param result 0x0004 - insufficient resources, 0x0006 - insufficient authorization 768 * @return status 769 */ 770 uint8_t l2cap_enhanced_decline_data_channels(uint16_t local_cid, uint16_t result); 771 772 /** 773 * @brief Provide credits for Enhanced Data Channel 774 * @param local_cid L2CAP LE Data Channel Identifier 775 * @param credits Number additional credits for peer 776 * @return status 777 */ 778 uint8_t l2cap_enhanced_provide_credits(uint16_t local_cid, uint16_t credits); 779 780 /** 781 * @brief Request emission of L2CAP_EVENT_DATA_CHANNEL_CAN_SEND_NOW as soon as possible 782 * @note L2CAP_EVENT_DATA_CHANNEL_CAN_SEND_NOW might be emitted during call to this function 783 * so packet handler should be ready to handle it 784 * @param local_cid L2CAP LE Data Channel Identifier 785 * @return status 786 */ 787 uint8_t l2cap_enhanced_data_channel_request_can_send_now_event(uint16_t local_cid); 788 789 /** 790 * @brief Reconfigure MPS/MTU of local channels 791 * @param num_cids 792 * @param local_cids array of local_cids to reconfigure 793 * @param receive_buffer_size buffer size equals MTU 794 * @param receive_buffers Array of buffers used for reassembly of L2CAP Information Frames into service data unit (SDU) with given MTU 795 * @return status 796 */ 797 uint8_t l2cap_enhanced_reconfigure(uint8_t num_cids, uint16_t * local_cids, int16_t receive_buffer_size, uint8_t ** receive_buffers); 798 799 /** 800 * @brief Send data via Enhanced Data Channel 801 * @note Since data larger then the maximum PDU needs to be segmented into multiple PDUs, data needs to stay valid until ... event 802 * @param local_cid L2CAP Enhanced Data Channel Identifier 803 * @param data data to send 804 * @param size data size 805 * @return status 806 */ 807 uint8_t l2cap_enhanced_send_data(uint16_t local_cid, const uint8_t * data, uint16_t size); 808 809 /** 810 * @brief Disconnect from Enhanced Data Channel 811 * @param local_cid L2CAP LE Data Channel Identifier 812 * @return status 813 */ 814 uint8_t l2cap_enhanced_disconnect(uint16_t local_cid); 815 816 /** 817 * @brief ERTM Set channel as busy. 818 * @note Can be cleared by l2cap_ertm_set_ready 819 * @param local_cid 820 * @return status 821 */ 822 uint8_t l2cap_ertm_set_busy(uint16_t local_cid); 823 824 /** 825 * @brief ERTM Set channel as ready 826 * @note Used after l2cap_ertm_set_busy 827 * @param local_cid 828 * @return status 829 */ 830 uint8_t l2cap_ertm_set_ready(uint16_t local_cid); 831 832 /** 833 * @brief De-Init L2CAP 834 */ 835 void l2cap_deinit(void); 836 837 /* API_END */ 838 839 #if defined __cplusplus 840 } 841 #endif 842 843 #endif // L2CAP_H 844