1 /** @file 2 * @brief Bluetooth L2CAP handling 3 */ 4 5 /* 6 * Copyright (c) 2015-2016 Intel Corporation 7 * 8 * SPDX-License-Identifier: Apache-2.0 9 */ 10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ 11 #define ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ 12 13 /** 14 * @brief L2CAP 15 * @defgroup bt_l2cap L2CAP 16 * @ingroup bluetooth 17 * @{ 18 */ 19 20 #include <sys/atomic.h> 21 #include <bluetooth/buf.h> 22 #include <bluetooth/conn.h> 23 #include <bluetooth/hci.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** L2CAP PDU header size, used for buffer size calculations */ 30 #define BT_L2CAP_HDR_SIZE 4 31 32 /** Maximum Transmission Unit (MTU) for an outgoing L2CAP PDU. */ 33 #define BT_L2CAP_TX_MTU (CONFIG_BT_L2CAP_TX_MTU) 34 35 /** Maximum Transmission Unit (MTU) for an incoming L2CAP PDU. */ 36 #define BT_L2CAP_RX_MTU (CONFIG_BT_BUF_ACL_RX_SIZE - BT_L2CAP_HDR_SIZE) 37 38 /** @brief Helper to calculate needed buffer size for L2CAP PDUs. 39 * Useful for creating buffer pools. 40 * 41 * @param mtu Needed L2CAP PDU MTU. 42 * 43 * @return Needed buffer size to match the requested L2CAP PDU MTU. 44 */ 45 #define BT_L2CAP_BUF_SIZE(mtu) BT_BUF_ACL_SIZE(BT_L2CAP_HDR_SIZE + (mtu)) 46 47 /** L2CAP SDU header size, used for buffer size calculations */ 48 #define BT_L2CAP_SDU_HDR_SIZE 2 49 50 /** @brief Maximum Transmission Unit for an unsegmented outgoing L2CAP SDU. 51 * 52 * The Maximum Transmission Unit for an outgoing L2CAP SDU when sent without 53 * segmentation, i.e a single L2CAP SDU will fit inside a single L2CAP PDU. 54 * 55 * The MTU for outgoing L2CAP SDUs with segmentation is defined by the 56 * size of the application buffer pool. 57 */ 58 #define BT_L2CAP_SDU_TX_MTU (BT_L2CAP_TX_MTU - BT_L2CAP_SDU_HDR_SIZE) 59 60 /** @brief Maximum Transmission Unit for an unsegmented incoming L2CAP SDU. 61 * 62 * The Maximum Transmission Unit for an incoming L2CAP SDU when sent without 63 * segmentation, i.e a single L2CAP SDU will fit inside a single L2CAP PDU. 64 * 65 * The MTU for incoming L2CAP SDUs with segmentation is defined by the 66 * size of the application buffer pool. The application will have to define 67 * an alloc_buf callback for the channel in order to support receiving 68 * segmented L2CAP SDUs. 69 */ 70 #define BT_L2CAP_SDU_RX_MTU (BT_L2CAP_RX_MTU - BT_L2CAP_SDU_HDR_SIZE) 71 72 /** @def BT_L2CAP_SDU_BUF_SIZE 73 * 74 * @brief Helper to calculate needed buffer size for L2CAP SDUs. 75 * Useful for creating buffer pools. 76 * 77 * @param mtu Required BT_L2CAP_*_SDU. 78 * 79 * @return Needed buffer size to match the requested L2CAP SDU MTU. 80 */ 81 #define BT_L2CAP_SDU_BUF_SIZE(mtu) BT_L2CAP_BUF_SIZE(BT_L2CAP_SDU_HDR_SIZE + (mtu)) 82 83 struct bt_l2cap_chan; 84 85 /** @typedef bt_l2cap_chan_destroy_t 86 * @brief Channel destroy callback 87 * 88 * @param chan Channel object. 89 */ 90 typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan); 91 92 /** @brief Life-span states of L2CAP CoC channel. 93 * 94 * Used only by internal APIs dealing with setting channel to proper state 95 * depending on operational context. 96 */ 97 typedef enum bt_l2cap_chan_state { 98 /** Channel disconnected */ 99 BT_L2CAP_DISCONNECTED, 100 /** Channel in connecting state */ 101 BT_L2CAP_CONNECT, 102 /** Channel in config state, BR/EDR specific */ 103 BT_L2CAP_CONFIG, 104 /** Channel ready for upper layer traffic on it */ 105 BT_L2CAP_CONNECTED, 106 /** Channel in disconnecting state */ 107 BT_L2CAP_DISCONNECT, 108 109 } __packed bt_l2cap_chan_state_t; 110 111 /** @brief Status of L2CAP channel. */ 112 typedef enum bt_l2cap_chan_status { 113 /** Channel output status */ 114 BT_L2CAP_STATUS_OUT, 115 116 /** @brief Channel shutdown status 117 * 118 * Once this status is notified it means the channel will no longer be 119 * able to transmit or receive data. 120 */ 121 BT_L2CAP_STATUS_SHUTDOWN, 122 123 /** @brief Channel encryption pending status */ 124 BT_L2CAP_STATUS_ENCRYPT_PENDING, 125 126 /* Total number of status - must be at the end of the enum */ 127 BT_L2CAP_NUM_STATUS, 128 } __packed bt_l2cap_chan_status_t; 129 130 /** @brief L2CAP Channel structure. */ 131 struct bt_l2cap_chan { 132 /** Channel connection reference */ 133 struct bt_conn *conn; 134 /** Channel operations reference */ 135 const struct bt_l2cap_chan_ops *ops; 136 sys_snode_t node; 137 bt_l2cap_chan_destroy_t destroy; 138 /* Response Timeout eXpired (RTX) timer */ 139 struct k_work_delayable rtx_work; 140 struct k_work_sync rtx_sync; 141 ATOMIC_DEFINE(status, BT_L2CAP_NUM_STATUS); 142 143 #if defined(CONFIG_BT_L2CAP_DYNAMIC_CHANNEL) 144 bt_l2cap_chan_state_t state; 145 /** Remote PSM to be connected */ 146 uint16_t psm; 147 /** Helps match request context during CoC */ 148 uint8_t ident; 149 bt_security_t required_sec_level; 150 #endif /* CONFIG_BT_L2CAP_DYNAMIC_CHANNEL */ 151 }; 152 153 /** @brief LE L2CAP Endpoint structure. */ 154 struct bt_l2cap_le_endpoint { 155 /** Endpoint Channel Identifier (CID) */ 156 uint16_t cid; 157 /** Endpoint Maximum Transmission Unit */ 158 uint16_t mtu; 159 /** Endpoint Maximum PDU payload Size */ 160 uint16_t mps; 161 /** Endpoint initial credits */ 162 uint16_t init_credits; 163 /** Endpoint credits */ 164 atomic_t credits; 165 }; 166 167 /** @brief LE L2CAP Channel structure. */ 168 struct bt_l2cap_le_chan { 169 /** Common L2CAP channel reference object */ 170 struct bt_l2cap_chan chan; 171 /** @brief Channel Receiving Endpoint. 172 * 173 * If the application has set an alloc_buf channel callback for the 174 * channel to support receiving segmented L2CAP SDUs the application 175 * should inititalize the MTU of the Receiving Endpoint. Otherwise the 176 * MTU of the receiving endpoint will be initialized to 177 * @ref BT_L2CAP_SDU_RX_MTU by the stack. 178 */ 179 struct bt_l2cap_le_endpoint rx; 180 181 /** Pending RX MTU on ECFC reconfigure, used internally by stack */ 182 uint16_t pending_rx_mtu; 183 184 /** Channel Transmission Endpoint */ 185 struct bt_l2cap_le_endpoint tx; 186 /** Channel Transmission queue */ 187 struct k_fifo tx_queue; 188 /** Channel Pending Transmission buffer */ 189 struct net_buf *tx_buf; 190 /** Channel Transmission work */ 191 struct k_work tx_work; 192 /** Segment SDU packet from upper layer */ 193 struct net_buf *_sdu; 194 uint16_t _sdu_len; 195 196 struct k_work rx_work; 197 struct k_fifo rx_queue; 198 }; 199 200 /** @def BT_L2CAP_LE_CHAN(_ch) 201 * @brief Helper macro getting container object of type bt_l2cap_le_chan 202 * address having the same container chan member address as object in question. 203 * 204 * @param _ch Address of object of bt_l2cap_chan type 205 * 206 * @return Address of in memory bt_l2cap_le_chan object type containing 207 * the address of in question object. 208 */ 209 #define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan) 210 211 /** @brief BREDR L2CAP Endpoint structure. */ 212 struct bt_l2cap_br_endpoint { 213 /** Endpoint Channel Identifier (CID) */ 214 uint16_t cid; 215 /** Endpoint Maximum Transmission Unit */ 216 uint16_t mtu; 217 }; 218 219 /** @brief BREDR L2CAP Channel structure. */ 220 struct bt_l2cap_br_chan { 221 /** Common L2CAP channel reference object */ 222 struct bt_l2cap_chan chan; 223 /** Channel Receiving Endpoint */ 224 struct bt_l2cap_br_endpoint rx; 225 /** Channel Transmission Endpoint */ 226 struct bt_l2cap_br_endpoint tx; 227 /* For internal use only */ 228 atomic_t flags[1]; 229 }; 230 231 /** @brief L2CAP Channel operations structure. */ 232 struct bt_l2cap_chan_ops { 233 /** @brief Channel connected callback 234 * 235 * If this callback is provided it will be called whenever the 236 * connection completes. 237 * 238 * @param chan The channel that has been connected 239 */ 240 void (*connected)(struct bt_l2cap_chan *chan); 241 242 /** @brief Channel disconnected callback 243 * 244 * If this callback is provided it will be called whenever the 245 * channel is disconnected, including when a connection gets 246 * rejected. 247 * 248 * @param chan The channel that has been Disconnected 249 */ 250 void (*disconnected)(struct bt_l2cap_chan *chan); 251 252 /** @brief Channel encrypt_change callback 253 * 254 * If this callback is provided it will be called whenever the 255 * security level changed (indirectly link encryption done) or 256 * authentication procedure fails. In both cases security initiator 257 * and responder got the final status (HCI status) passed by 258 * related to encryption and authentication events from local host's 259 * controller. 260 * 261 * @param chan The channel which has made encryption status changed. 262 * @param status HCI status of performed security procedure caused 263 * by channel security requirements. The value is populated 264 * by HCI layer and set to 0 when success and to non-zero (reference to 265 * HCI Error Codes) when security/authentication failed. 266 */ 267 void (*encrypt_change)(struct bt_l2cap_chan *chan, uint8_t hci_status); 268 269 /** @brief Channel alloc_seg callback 270 * 271 * If this callback is provided the channel will use it to allocate 272 * buffers to store segments. This avoids wasting big SDU buffers with 273 * potentially much smaller PDUs. If this callback is supplied, it must 274 * return a valid buffer. 275 * 276 * @param chan The channel requesting a buffer. 277 * 278 * @return Allocated buffer. 279 */ 280 struct net_buf *(*alloc_seg)(struct bt_l2cap_chan *chan); 281 282 /** @brief Channel alloc_buf callback 283 * 284 * If this callback is provided the channel will use it to allocate 285 * buffers to store incoming data. Channels that requires segmentation 286 * must set this callback. 287 * If the application has not set a callback the L2CAP SDU MTU will be 288 * truncated to @ref BT_L2CAP_SDU_RX_MTU. 289 * 290 * @param chan The channel requesting a buffer. 291 * 292 * @return Allocated buffer. 293 */ 294 struct net_buf *(*alloc_buf)(struct bt_l2cap_chan *chan); 295 296 /** @brief Channel recv callback 297 * 298 * @param chan The channel receiving data. 299 * @param buf Buffer containing incoming data. 300 * 301 * @return 0 in case of success or negative value in case of error. 302 * @return -EINPROGRESS in case where user has to confirm once the data 303 * has been processed by calling 304 * @ref bt_l2cap_chan_recv_complete passing back 305 * the buffer received with its original user_data 306 * which contains the number of segments/credits 307 * used by the packet. 308 */ 309 int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf); 310 311 /** @brief Channel sent callback 312 * 313 * If this callback is provided it will be called whenever a SDU has 314 * been completely sent. 315 * 316 * @param chan The channel which has sent data. 317 */ 318 void (*sent)(struct bt_l2cap_chan *chan); 319 320 /** @brief Channel status callback 321 * 322 * If this callback is provided it will be called whenever the 323 * channel status changes. 324 * 325 * @param chan The channel which status changed 326 * @param status The channel status 327 */ 328 void (*status)(struct bt_l2cap_chan *chan, atomic_t *status); 329 330 /* @brief Channel released callback 331 * 332 * If this callback is set it is called when the stack has release all 333 * references to the channel object. 334 */ 335 void (*released)(struct bt_l2cap_chan *chan); 336 337 /** @brief Channel reconfigured callback 338 * 339 * If this callback is provided it will be called whenever peer or 340 * local device requested reconfiguration. Application may check 341 * updated MTU and MPS values by inspecting chan->le endpoints. 342 * 343 * @param chan The channel which was reconfigured 344 */ 345 void (*reconfigured)(struct bt_l2cap_chan *chan); 346 }; 347 348 /** @def BT_L2CAP_CHAN_SEND_RESERVE 349 * @brief Headroom needed for outgoing L2CAP PDUs. 350 */ 351 #define BT_L2CAP_CHAN_SEND_RESERVE (BT_L2CAP_BUF_SIZE(0)) 352 353 /** @def BT_L2CAP_SDU_CHAN_SEND_RESERVE 354 * @brief Headroom needed for outgoing L2CAP SDUs. 355 */ 356 #define BT_L2CAP_SDU_CHAN_SEND_RESERVE (BT_L2CAP_SDU_BUF_SIZE(0)) 357 358 /** @brief L2CAP Server structure. */ 359 struct bt_l2cap_server { 360 /** @brief Server PSM. 361 * 362 * Possible values: 363 * 0 A dynamic value will be auto-allocated when 364 * bt_l2cap_server_register() is called. 365 * 366 * 0x0001-0x007f Standard, Bluetooth SIG-assigned fixed values. 367 * 368 * 0x0080-0x00ff Dynamically allocated. May be pre-set by the 369 * application before server registration (not 370 * recommended however), or auto-allocated by the 371 * stack if the app gave 0 as the value. 372 */ 373 uint16_t psm; 374 375 /** Required minimum security level */ 376 bt_security_t sec_level; 377 378 /** @brief Server accept callback 379 * 380 * This callback is called whenever a new incoming connection requires 381 * authorization. 382 * 383 * @param conn The connection that is requesting authorization 384 * @param chan Pointer to received the allocated channel 385 * 386 * @return 0 in case of success or negative value in case of error. 387 * @return -ENOMEM if no available space for new channel. 388 * @return -EACCES if application did not authorize the connection. 389 * @return -EPERM if encryption key size is too short. 390 */ 391 int (*accept)(struct bt_conn *conn, struct bt_l2cap_chan **chan); 392 393 sys_snode_t node; 394 }; 395 396 /** @brief Register L2CAP server. 397 * 398 * Register L2CAP server for a PSM, each new connection is authorized using 399 * the accept() callback which in case of success shall allocate the channel 400 * structure to be used by the new connection. 401 * 402 * For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should 403 * be assigned to server->psm before calling this API. For dynamic PSMs 404 * (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value 405 * (this is however not recommended) or be left as 0, in which case upon 406 * return a newly allocated value will have been assigned to it. For 407 * dynamically allocated values the expectation is that it's exposed through 408 * a GATT service, and that's how L2CAP clients discover how to connect to 409 * the server. 410 * 411 * @param server Server structure. 412 * 413 * @return 0 in case of success or negative value in case of error. 414 */ 415 int bt_l2cap_server_register(struct bt_l2cap_server *server); 416 417 /** @brief Register L2CAP server on BR/EDR oriented connection. 418 * 419 * Register L2CAP server for a PSM, each new connection is authorized using 420 * the accept() callback which in case of success shall allocate the channel 421 * structure to be used by the new connection. 422 * 423 * @param server Server structure. 424 * 425 * @return 0 in case of success or negative value in case of error. 426 */ 427 int bt_l2cap_br_server_register(struct bt_l2cap_server *server); 428 429 /** @brief Connect Enhanced Credit Based L2CAP channels 430 * 431 * Connect up to 5 L2CAP channels by PSM, once the connection is completed 432 * each channel connected() callback will be called. If the connection is 433 * rejected disconnected() callback is called instead. 434 * 435 * @param conn Connection object. 436 * @param chans Array of channel objects. 437 * @param psm Channel PSM to connect to. 438 * 439 * @return 0 in case of success or negative value in case of error. 440 */ 441 int bt_l2cap_ecred_chan_connect(struct bt_conn *conn, 442 struct bt_l2cap_chan **chans, uint16_t psm); 443 444 /** @brief Reconfigure Enhanced Credit Based L2CAP channels 445 * 446 * Reconfigure up to 5 L2CAP channels. Channels must be from the same bt_conn. 447 * Once reconfiguration is completed each channel reconfigured() callback will 448 * be called. MTU cannot be decreased on any of provided channels. 449 * 450 * @param chans Array of channel objects. Null-terminated. Elements after the 451 * first 5 are silently ignored. 452 * @param mtu Channel MTU to reconfigure to. 453 * 454 * @return 0 in case of success or negative value in case of error. 455 */ 456 int bt_l2cap_ecred_chan_reconfigure(struct bt_l2cap_chan **chans, uint16_t mtu); 457 458 /** @brief Connect L2CAP channel 459 * 460 * Connect L2CAP channel by PSM, once the connection is completed channel 461 * connected() callback will be called. If the connection is rejected 462 * disconnected() callback is called instead. 463 * Channel object passed (over an address of it) as second parameter shouldn't 464 * be instantiated in application as standalone. Instead of, application should 465 * create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for 466 * LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API 467 * the location (address) of bt_l2cap_chan type object which is a member 468 * of both transport dedicated objects. 469 * 470 * @param conn Connection object. 471 * @param chan Channel object. 472 * @param psm Channel PSM to connect to. 473 * 474 * @return 0 in case of success or negative value in case of error. 475 */ 476 int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan, 477 uint16_t psm); 478 479 /** @brief Disconnect L2CAP channel 480 * 481 * Disconnect L2CAP channel, if the connection is pending it will be 482 * canceled and as a result the channel disconnected() callback is called. 483 * Regarding to input parameter, to get details see reference description 484 * to bt_l2cap_chan_connect() API above. 485 * 486 * @param chan Channel object. 487 * 488 * @return 0 in case of success or negative value in case of error. 489 */ 490 int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan); 491 492 /** @brief Send data to L2CAP channel 493 * 494 * Send data from buffer to the channel. If credits are not available, buf will 495 * be queued and sent as and when credits are received from peer. 496 * Regarding to first input parameter, to get details see reference description 497 * to bt_l2cap_chan_connect() API above. 498 * 499 * When sending L2CAP data over an BR/EDR connection the application is sending 500 * L2CAP PDUs. The application is required to have reserved 501 * @ref BT_L2CAP_CHAN_SEND_RESERVE bytes in the buffer before sending. 502 * The application should use the BT_L2CAP_BUF_SIZE() helper to correctly 503 * size the buffers for the for the outgoing buffer pool. 504 * 505 * When sending L2CAP data over an LE connection the applicatios is sending 506 * L2CAP SDUs. The application can optionally reserve 507 * @ref BT_L2CAP_SDU_CHAN_SEND_RESERVE bytes in the buffer before sending. 508 * By reserving bytes in the buffer the stack can use this buffer as a segment 509 * directly, otherwise it will have to allocate a new segment for the first 510 * segment. 511 * If the application is reserving the bytes it should use the 512 * BT_L2CAP_BUF_SIZE() helper to correctly size the buffers for the for the 513 * outgoing buffer pool. 514 * When segmenting an L2CAP SDU into L2CAP PDUs the stack will first attempt 515 * to allocate buffers from the original buffer pool of the L2CAP SDU before 516 * using the stacks own buffer pool. 517 * 518 * @note Buffer ownership is transferred to the stack in case of success, in 519 * case of an error the caller retains the ownership of the buffer. 520 * 521 * @return Bytes sent in case of success or negative value in case of error. 522 */ 523 int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf); 524 525 /** @brief Complete receiving L2CAP channel data 526 * 527 * Complete the reception of incoming data. This shall only be called if the 528 * channel recv callback has returned -EINPROGRESS to process some incoming 529 * data. The buffer shall contain the original user_data as that is used for 530 * storing the credits/segments used by the packet. 531 * 532 * @param chan Channel object. 533 * @param buf Buffer containing the data. 534 * 535 * @return 0 in case of success or negative value in case of error. 536 */ 537 int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan, 538 struct net_buf *buf); 539 540 #ifdef __cplusplus 541 } 542 #endif 543 544 /** 545 * @} 546 */ 547 548 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ */ 549
