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 <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 header size, used for buffer size calculations */ 30 #define BT_L2CAP_HDR_SIZE 4 31 32 /** @def BT_L2CAP_BUF_SIZE 33 * 34 * @brief Helper to calculate needed outgoing buffer size, useful e.g. for 35 * creating buffer pools. 36 * 37 * @param mtu Needed L2CAP MTU. 38 * 39 * @return Needed buffer size to match the requested L2CAP MTU. 40 */ 41 #define BT_L2CAP_BUF_SIZE(mtu) (BT_BUF_RESERVE + \ 42 BT_HCI_ACL_HDR_SIZE + BT_L2CAP_HDR_SIZE + \ 43 (mtu)) 44 45 struct bt_l2cap_chan; 46 47 /** @typedef bt_l2cap_chan_destroy_t 48 * @brief Channel destroy callback 49 * 50 * @param chan Channel object. 51 */ 52 typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan); 53 54 /** @brief Life-span states of L2CAP CoC channel. 55 * 56 * Used only by internal APIs dealing with setting channel to proper state 57 * depending on operational context. 58 */ 59 typedef enum bt_l2cap_chan_state { 60 /** Channel disconnected */ 61 BT_L2CAP_DISCONNECTED, 62 /** Channel in connecting state */ 63 BT_L2CAP_CONNECT, 64 /** Channel in config state, BR/EDR specific */ 65 BT_L2CAP_CONFIG, 66 /** Channel ready for upper layer traffic on it */ 67 BT_L2CAP_CONNECTED, 68 /** Channel in disconnecting state */ 69 BT_L2CAP_DISCONNECT, 70 71 } __packed bt_l2cap_chan_state_t; 72 73 /** @brief Status of L2CAP channel. */ 74 typedef enum bt_l2cap_chan_status { 75 /** Channel output status */ 76 BT_L2CAP_STATUS_OUT, 77 78 /** @brief Channel shutdown status 79 * 80 * Once this status is notified it means the channel will no longer be 81 * able to transmit or receive data. 82 */ 83 BT_L2CAP_STATUS_SHUTDOWN, 84 85 /** @brief Channel encryption pending status */ 86 BT_L2CAP_STATUS_ENCRYPT_PENDING, 87 88 /* Total number of status - must be at the end of the enum */ 89 BT_L2CAP_NUM_STATUS, 90 } __packed bt_l2cap_chan_status_t; 91 92 /** @brief L2CAP Channel structure. */ 93 struct bt_l2cap_chan { 94 /** Channel connection reference */ 95 struct bt_conn *conn; 96 /** Channel operations reference */ 97 const struct bt_l2cap_chan_ops *ops; 98 sys_snode_t node; 99 bt_l2cap_chan_destroy_t destroy; 100 /* Response Timeout eXpired (RTX) timer */ 101 struct k_delayed_work rtx_work; 102 ATOMIC_DEFINE(status, BT_L2CAP_NUM_STATUS); 103 104 #if defined(CONFIG_BT_L2CAP_DYNAMIC_CHANNEL) 105 bt_l2cap_chan_state_t state; 106 /** Remote PSM to be connected */ 107 u16_t psm; 108 /** Helps match request context during CoC */ 109 u8_t ident; 110 bt_security_t required_sec_level; 111 #endif /* CONFIG_BT_L2CAP_DYNAMIC_CHANNEL */ 112 }; 113 114 /** @brief LE L2CAP Endpoint structure. */ 115 struct bt_l2cap_le_endpoint { 116 /** Endpoint CID */ 117 u16_t cid; 118 /** Endpoint Maximum Transmission Unit */ 119 u16_t mtu; 120 /** Endpoint Maximum PDU payload Size */ 121 u16_t mps; 122 /** Endpoint initial credits */ 123 u16_t init_credits; 124 /** Endpoint credits */ 125 atomic_t credits; 126 }; 127 128 /** @brief LE L2CAP Channel structure. */ 129 struct bt_l2cap_le_chan { 130 /** Common L2CAP channel reference object */ 131 struct bt_l2cap_chan chan; 132 /** Channel Receiving Endpoint */ 133 struct bt_l2cap_le_endpoint rx; 134 /** Channel Transmission Endpoint */ 135 struct bt_l2cap_le_endpoint tx; 136 /** Channel Transmission queue */ 137 struct kfifo tx_queue; 138 /** Channel Pending Transmission buffer */ 139 struct net_buf *tx_buf; 140 /** Channel Transmission work */ 141 struct k_work tx_work; 142 /** Segment SDU packet from upper layer */ 143 struct net_buf *_sdu; 144 u16_t _sdu_len; 145 146 struct k_work rx_work; 147 struct kfifo rx_queue; 148 }; 149 150 /** @def BT_L2CAP_LE_CHAN(_ch) 151 * @brief Helper macro getting container object of type bt_l2cap_le_chan 152 * address having the same container chan member address as object in question. 153 * 154 * @param _ch Address of object of bt_l2cap_chan type 155 * 156 * @return Address of in memory bt_l2cap_le_chan object type containing 157 * the address of in question object. 158 */ 159 #define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan) 160 161 /** @brief BREDR L2CAP Endpoint structure. */ 162 struct bt_l2cap_br_endpoint { 163 /** Endpoint CID */ 164 u16_t cid; 165 /** Endpoint Maximum Transmission Unit */ 166 u16_t mtu; 167 }; 168 169 /** @brief BREDR L2CAP Channel structure. */ 170 struct bt_l2cap_br_chan { 171 /** Common L2CAP channel reference object */ 172 struct bt_l2cap_chan chan; 173 /** Channel Receiving Endpoint */ 174 struct bt_l2cap_br_endpoint rx; 175 /** Channel Transmission Endpoint */ 176 struct bt_l2cap_br_endpoint tx; 177 /* For internal use only */ 178 atomic_t flags[1]; 179 }; 180 181 /** @brief L2CAP Channel operations structure. */ 182 struct bt_l2cap_chan_ops { 183 /** @brief Channel connected callback 184 * 185 * If this callback is provided it will be called whenever the 186 * connection completes. 187 * 188 * @param chan The channel that has been connected 189 */ 190 void (*connected)(struct bt_l2cap_chan *chan); 191 192 /** @brief Channel disconnected callback 193 * 194 * If this callback is provided it will be called whenever the 195 * channel is disconnected, including when a connection gets 196 * rejected. 197 * 198 * @param chan The channel that has been Disconnected 199 */ 200 void (*disconnected)(struct bt_l2cap_chan *chan); 201 202 /** @brief Channel encrypt_change callback 203 * 204 * If this callback is provided it will be called whenever the 205 * security level changed (indirectly link encryption done) or 206 * authentication procedure fails. In both cases security initiator 207 * and responder got the final status (HCI status) passed by 208 * related to encryption and authentication events from local host's 209 * controller. 210 * 211 * @param chan The channel which has made encryption status changed. 212 * @param status HCI status of performed security procedure caused 213 * by channel security requirements. The value is populated 214 * by HCI layer and set to 0 when success and to non-zero (reference to 215 * HCI Error Codes) when security/authentication failed. 216 */ 217 void (*encrypt_change)(struct bt_l2cap_chan *chan, u8_t hci_status); 218 219 /** @brief Channel alloc_buf callback 220 * 221 * If this callback is provided the channel will use it to allocate 222 * buffers to store incoming data. 223 * 224 * @param chan The channel requesting a buffer. 225 * 226 * @return Allocated buffer. 227 */ 228 struct net_buf *(*alloc_buf)(struct bt_l2cap_chan *chan); 229 230 /** @brief Channel recv callback 231 * 232 * @param chan The channel receiving data. 233 * @param buf Buffer containing incoming data. 234 * 235 * @return 0 in case of success or negative value in case of error. 236 * @return -EINPROGRESS in case where user has to confirm once the data 237 * has been processed by calling 238 * @ref bt_l2cap_chan_recv_complete passing back 239 * the buffer received with its original user_data 240 * which contains the number of segments/credits 241 * used by the packet. 242 */ 243 int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf); 244 245 /** @brief Channel sent callback 246 * 247 * If this callback is provided it will be called whenever a SDU has 248 * been completely sent. 249 * 250 * @param chan The channel which has sent data. 251 */ 252 void (*sent)(struct bt_l2cap_chan *chan); 253 254 /** @brief Channel status callback 255 * 256 * If this callback is provided it will be called whenever the 257 * channel status changes. 258 * 259 * @param chan The channel which status changed 260 * @param status The channel status 261 */ 262 void (*status)(struct bt_l2cap_chan *chan, atomic_t *status); 263 264 /* @brief Channel released callback 265 * 266 * If this callback is set it is called when the stack has release all 267 * references to the channel object. 268 */ 269 void (*released)(struct bt_l2cap_chan *chan); 270 }; 271 272 /** @def BT_L2CAP_CHAN_SEND_RESERVE 273 * @brief Headroom needed for outgoing buffers 274 */ 275 #define BT_L2CAP_CHAN_SEND_RESERVE (BT_BUF_RESERVE + 4 + 4) 276 277 /** @brief L2CAP Server structure. */ 278 struct bt_l2cap_server { 279 /** @brief Server PSM. 280 * 281 * Possible values: 282 * 0 A dynamic value will be auto-allocated when 283 * bt_l2cap_server_register() is called. 284 * 285 * 0x0001-0x007f Standard, Bluetooth SIG-assigned fixed values. 286 * 287 * 0x0080-0x00ff Dynamically allocated. May be pre-set by the 288 * application before server registration (not 289 * recommended however), or auto-allocated by the 290 * stack if the app gave 0 as the value. 291 */ 292 u16_t psm; 293 294 /** Required minimim security level */ 295 bt_security_t sec_level; 296 297 /** @brief Server accept callback 298 * 299 * This callback is called whenever a new incoming connection requires 300 * authorization. 301 * 302 * @param conn The connection that is requesting authorization 303 * @param chan Pointer to received the allocated channel 304 * 305 * @return 0 in case of success or negative value in case of error. 306 * @return -ENOMEM if no available space for new channel. 307 * @return -EACCES if application did not authorize the connection. 308 * @return -EPERM if encryption key size is too short. 309 */ 310 int (*accept)(struct bt_conn *conn, struct bt_l2cap_chan **chan); 311 312 sys_snode_t node; 313 }; 314 315 /** @brief Register L2CAP server. 316 * 317 * Register L2CAP server for a PSM, each new connection is authorized using 318 * the accept() callback which in case of success shall allocate the channel 319 * structure to be used by the new connection. 320 * 321 * For fixed, SIG-assigned PSMs (in the range 0x0001-0x007f) the PSM should 322 * be assigned to server->psm before calling this API. For dynamic PSMs 323 * (in the range 0x0080-0x00ff) server->psm may be pre-set to a given value 324 * (this is however not recommended) or be left as 0, in which case upon 325 * return a newly allocated value will have been assigned to it. For 326 * dynamically allocated values the expectation is that it's exposed through 327 * a GATT service, and that's how L2CAP clients discover how to connect to 328 * the server. 329 * 330 * @param server Server structure. 331 * 332 * @return 0 in case of success or negative value in case of error. 333 */ 334 int bt_l2cap_server_register(struct bt_l2cap_server *server); 335 336 /** @brief Register L2CAP server on BR/EDR oriented connection. 337 * 338 * Register L2CAP server for a PSM, each new connection is authorized using 339 * the accept() callback which in case of success shall allocate the channel 340 * structure to be used by the new connection. 341 * 342 * @param server Server structure. 343 * 344 * @return 0 in case of success or negative value in case of error. 345 */ 346 int bt_l2cap_br_server_register(struct bt_l2cap_server *server); 347 348 /** @brief Connect Enhanced Credit Based L2CAP channels 349 * 350 * Connect up to 5 L2CAP channels by PSM, once the connection is completed 351 * each channel connected() callback will be called. If the connection is 352 * rejected disconnected() callback is called instead. 353 * 354 * @param conn Connection object. 355 * @param chans Array of channel objects. 356 * @param psm Channel PSM to connect to. 357 * 358 * @return 0 in case of success or negative value in case of error. 359 */ 360 int bt_l2cap_ecred_chan_connect(struct bt_conn *conn, 361 struct bt_l2cap_chan **chans, u16_t psm); 362 363 /** @brief Connect L2CAP channel 364 * 365 * Connect L2CAP channel by PSM, once the connection is completed channel 366 * connected() callback will be called. If the connection is rejected 367 * disconnected() callback is called instead. 368 * Channel object passed (over an address of it) as second parameter shouldn't 369 * be instantiated in application as standalone. Instead of, application should 370 * create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for 371 * LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API 372 * the location (address) of bt_l2cap_chan type object which is a member 373 * of both transport dedicated objects. 374 * 375 * @param conn Connection object. 376 * @param chan Channel object. 377 * @param psm Channel PSM to connect to. 378 * 379 * @return 0 in case of success or negative value in case of error. 380 */ 381 int bt_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan, 382 u16_t psm); 383 384 /** @brief Disconnect L2CAP channel 385 * 386 * Disconnect L2CAP channel, if the connection is pending it will be 387 * canceled and as a result the channel disconnected() callback is called. 388 * Regarding to input parameter, to get details see reference description 389 * to bt_l2cap_chan_connect() API above. 390 * 391 * @param chan Channel object. 392 * 393 * @return 0 in case of success or negative value in case of error. 394 */ 395 int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan); 396 397 /** @brief Send data to L2CAP channel 398 * 399 * Send data from buffer to the channel. If credits are not available, buf will 400 * be queued and sent as and when credits are received from peer. 401 * Regarding to first input parameter, to get details see reference description 402 * to bt_l2cap_chan_connect() API above. 403 * 404 * @return Bytes sent in case of success or negative value in case of error. 405 */ 406 int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf); 407 408 /** @brief Complete receiving L2CAP channel data 409 * 410 * Complete the reception of incoming data. This shall only be called if the 411 * channel recv callback has returned -EINPROGRESS to process some incoming 412 * data. The buffer shall contain the original user_data as that is used for 413 * storing the credits/segments used by the packet. 414 * 415 * @param chan Channel object. 416 * @param buf Buffer containing the data. 417 * 418 * @return 0 in case of success or negative value in case of error. 419 */ 420 int bt_l2cap_chan_recv_complete(struct bt_l2cap_chan *chan, 421 struct net_buf *buf); 422 423 #ifdef __cplusplus 424 } 425 #endif 426 427 /** 428 * @} 429 */ 430 431 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_H_ */ 432