1 /** 2 **************************************************************************************** 3 * 4 * @file ble_l2cap.h 5 * 6 * @brief BLE L2CAP API 7 * 8 **************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup BLE 40 * @{ 41 */ 42 43 /** 44 @addtogroup BLE_L2CAP Logical Link Control and Adaptation Protocol (L2CAP) 45 @{ 46 @brief Definitions and prototypes for the L2CAP interface. 47 */ 48 49 #ifndef __BLE_L2CAP_H__ 50 #define __BLE_L2CAP_H__ 51 52 #include <stdint.h> 53 #include <stdbool.h> 54 #include "gr55xx_sys_cfg.h" 55 56 /** @addtogroup BLE_L2CAP_ENUMERATIONS Enumerations 57 * @{ */ 58 59 /** @brief LE credit based disconnection reasons. */ 60 typedef enum { 61 REMOTE_USER_TERM_CON = 0x00, /**< Remote user terminates the connection. */ 62 LOCAL_USER_TERM_CON = 0x01, /**< Local user terminates the connection. */ 63 } lecb_disconnect_reason_t; 64 65 /** @} */ 66 67 /** @addtogroup BLE_L2CAP_STRUCTURES Structures 68 * @{ */ 69 /** @brief The parameter of LE credit based connection request packet sending. 70 * @note The le_psm should be registered by the peer device, otherwise the peer device will reject 71 * this request with result of LE_PSM not supported. 72 * @note The local_cid should be 0x0040-0x007F. If the local_cid is set to 0, the stack will assign it dynamically. 73 * @note The local_credit is required to be sure that at least one SDU can be received, 74 * otherwise the stack will use the default value: (MTU + MPS + 1) /MPS + 1. 75 * @note The MTU range is [23~max_mtu]. 76 * @note The MPS range is [23~max_mps]. 77 * @note About max_mtu and max_mps config, please see @ref ble_gap_l2cap_params_set. 78 */ 79 typedef struct { 80 uint16_t le_psm; /**< The le_psm number. */ 81 uint16_t local_cid; /**< The local CID. */ 82 uint16_t local_credits; /**< The local credits indicate the number of LE-frames that the peer devicecan send 83 to the L2CAP layer entity sending the LE Credit Based Connection Request. */ 84 uint16_t mtu; /**< The MTU field specifies the maximum SDU size (in octets) that the L2CAP layer 85 entity sending the LE Credit Based Connection Request 86 can receive on this channel. */ 87 uint16_t mps; /**< The MPS field specifies the maximum payload size (in octets) that 88 the L2CAP layer entity sending the LE Credit Based Connection Request 89 is capable of receiving on this channel. */ 90 } lecb_conn_req_t; 91 92 /** @brief LE credit based connection confirm parameter. 93 * @note The accept flag indicates whether the App accepts the LE Credit Based connection request. 94 * @note The peer_cid represents the channel endpoint on the peer device. 95 * @note The local_cid should be 0x0040-0x007F. If the local_cid is set to 0, the stack will assign it dynamically. 96 * @note The local_credits required to be sure that at least one SDU can be received, otherwise the stack 97 * will use the default value: (MTU + MPS + 1) /MPS + 1. 98 * @note The MTU range is [23~max_mtu]. 99 * @note The MPS range is [23~max_mps]. 100 * @note About the max_mtu and max_mps config, please see @ref ble_gap_l2cap_params_set. 101 */ 102 typedef struct { 103 bool accept; /**< Whether to accept the connection request. */ 104 uint16_t peer_cid; /**< It represents the channel endpoint on the device sending the request 105 and receiving the response. */ 106 uint16_t local_cid; /**< Local CID. */ 107 uint16_t local_credits; /**< It indicates the number of LE-frames that the peer device can send to the 108 L2CAP layer entity sending the LE Credit Based Connection Respone. */ 109 uint16_t mtu; /**< The MTU field specifies the maximum SDU size (in octets) that the L2CAP layer entity 110 sending the LE Credit Based Connection Request can receive on this channel. */ 111 uint16_t mps; /**< The MPS field specifies the maximum payload size (in octets) that the L2CAP layer 112 entity sending the LE Credit Based Connection Request is capable of receiving 113 on this channel. */ 114 } lecb_cfm_conn_t; 115 116 /** @brief LE flow control credit packet parameter. */ 117 typedef struct { 118 uint16_t local_cid; /**< The local source channel ID. */ 119 uint16_t credits; /**< Number of credits that the receiving device can increment. */ 120 } lecb_add_credits_t; 121 122 /** @brief SDU packet parameter. 123 * @note The length should be less than peer_mtu when sending sdu packet. 124 * @note The credits is 0 if this packet is being sent, or it represents the number of credits consumed 125 * by this sdu if this packet is received. 126 * @note When the application receives a sdu, it should firstly copy this sdu packet before handling it, 127 * because the stack will free it after invoking the callback function. 128 * @note Similarly, the application should free the packet if it is malloced 129 * after invoking the function to send sdu packet. 130 */ 131 typedef struct { 132 uint16_t cid; /**< The local source channel. */ 133 uint16_t credits; /**< The credits is 0 if this packet is being sent, 134 otherwise it represents the number of credits consumed by the sdu. */ 135 uint16_t length; /**< The lenght of data. */ 136 uint8_t data[__ARRAY_EMPTY]; /**< The data of this sdu packet. */ 137 } lecb_sdu_t; 138 139 /** @brief Receive LE credit based connection request packet indication. */ 140 typedef struct { 141 uint16_t le_psm; /**< Le_psm number that should be registered by local device. */ 142 uint16_t peer_cid; /**< It represents the channel endpoint on the device sending the request 143 and receiving the response. */ 144 uint16_t peer_mtu; /**< It indicates the maximum SDU size (in octets) that the L2CAP layer entity sending 145 the LE Credit Based Connection Request can receive on this channel. */ 146 uint16_t peer_mps; /**< It indicates the maximum payload size (in octets) that the L2CAP layer entity sending 147 the LE Credit Based Connection Request is capable of receiving on this channe. */ 148 } lecb_conn_req_ind_t; 149 150 /** @brief LE credit based connection created indication. */ 151 typedef struct { 152 uint16_t le_psm; /**< Le_psm number. */ 153 uint16_t local_cid; /**< The local source channel ID. */ 154 uint16_t local_credits; /**< It indicates the number of LE-frames that the local device can receive. */ 155 uint16_t peer_credits; /**< It indicates the number of LE-frames that the peer device can receive. */ 156 uint16_t peer_mtu; /**< It indicates the maximum SDU size (in octets) that the L2CAP layer entity sending 157 the LE Credit Based Connection Request can receive on this channel. */ 158 uint16_t peer_mps; /**< It indicates the maximum payload size (in octets) that the L2CAP layer entity sending 159 the LE Credit Based Connection Request is capable of receiving on this channe. */ 160 } lecb_conn_ind_t; 161 162 /** @brief LE credit based disconnect indication. */ 163 typedef struct { 164 uint16_t local_cid; /**< The local source channel ID. */ 165 uint8_t reason; /**< The reason for disconnection, see @ref lecb_disconnect_reason_t . */ 166 } lecb_disconn_ind_t; 167 168 /** @brief LE credit based connection addition indication. */ 169 typedef struct { 170 uint16_t local_cid; /**< The local source channel ID. */ 171 uint16_t peer_added_credits; /**< Represent number of credits the receiving device can increment. */ 172 } lecb_add_credits_ind_t; 173 174 /** @brief LE credit based SDU sending complete event. */ 175 typedef struct { 176 uint16_t cid; /**< Channel ID that is the local CID. */ 177 uint16_t credits; /**< Number of peer credit used. */ 178 } lecb_sdu_send_evt_t; 179 180 /** @brief Callback registered by APP. */ 181 typedef struct { 182 /**< Callback for receiving LE credit based connection request. */ 183 void (*app_l2cap_lecb_conn_req_cb)(uint8_t conn_idx, lecb_conn_req_ind_t *p_conn_req); 184 /**< Callback for receiving LE credit based connection created indication. */ 185 void (*app_l2cap_lecb_conn_cb)(uint8_t conn_idx, uint8_t status, lecb_conn_ind_t *p_conn_ind); 186 /**< Callback for receiving LE credit based connection addition indication. */ 187 void (*app_l2cap_lecb_add_credits_ind_cb)(uint8_t conn_idx, lecb_add_credits_ind_t *p_add_credits_ind); 188 /**< Callback for receiving LE credit based disconnection indication. */ 189 void (*app_l2cap_lecb_disconn_cb)(uint8_t conn_idx, uint8_t status, lecb_disconn_ind_t *p_disconn_ind); 190 /**< Callback for receiving SDU packet. */ 191 void (*app_l2cap_lecb_sdu_recv_cb)(uint8_t conn_idx, lecb_sdu_t *p_sdu); 192 /**< Callback for sending SDU operation complete event. */ 193 void (*app_l2cap_lecb_sdu_send_cb)(uint8_t conn_idx, uint8_t status, lecb_sdu_send_evt_t *p_sdu_send_evt); 194 /**< Callback for LE credit add complete event. */ 195 void (*app_l2cap_lecb_credit_add_cmp_cb)(uint8_t conn_idx, uint8_t status, uint16_t local_cid); 196 } l2cap_lecb_cb_fun_t; 197 198 199 /** @} */ 200 201 /** @addtogroup BLE_L2CAP_FUNCTIONS Functions 202 * @{ */ 203 /** 204 **************************************************************************************** 205 * @brief Create the LE credit based connection. 206 * @note After the COC created, the callback @ref l2cap_lecb_cb_fun_t::app_l2cap_lecb_conn_cb will be called. 207 * 208 * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0, 209 * and the index will be increased one by one. 210 * @param[in] p_conn_req: Pointer to the LE Credit Based Connection Request structure. 211 * 212 * @retval ::SDK_SUCCESS: The LE Credit Based connection request is successfully set to the BLE stack. 213 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 214 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 215 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 216 **************************************************************************************** 217 */ 218 uint16_t ble_l2cap_lecb_conn_create(uint8_t conn_idx, const lecb_conn_req_t *p_conn_req); 219 220 /** 221 **************************************************************************************** 222 * @brief Confirm the LE credit based connection after receiving the connection request packet from the peer device. 223 * @note This function should be invoked in the handle of callback @ref l2cap_lecb_cb_fun_t:app_l2cap_lecb_conn_req_cb. 224 * And after the COC created, the callback @ref l2cap_lecb_cb_fun_t::app_l2cap_lecb_conn_cb should be called. 225 * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0 and 226 * the index will be increased one by one. 227 * @param[in] p_cfm_conn: Pointer to the LE Credit Based Connection Confirm structure. 228 * 229 * @retval ::SDK_SUCCESS: The LE Credit Based connection confirmation is successfully set to the BLE stack. 230 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 231 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 232 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 233 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 234 **************************************************************************************** 235 */ 236 uint16_t ble_l2cap_lecb_conn_cfm(uint8_t conn_idx, const lecb_cfm_conn_t *p_cfm_conn); 237 238 /** 239 **************************************************************************************** 240 * @brief Disconnect the LE credit based connection. 241 * @note After COC disconnected, the callback @ref l2cap_lecb_cb_fun_t::app_l2cap_lecb_disconn_cb should be called. 242 * 243 * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0 and 244 * the index will be increased one by one. 245 * @param[in] local_cid: The local source channel ID. 246 * 247 * @retval ::SDK_SUCCESS: LE Credit Based disconnection request is successfully set to the BLE stack. 248 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 249 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 250 **************************************************************************************** 251 */ 252 uint16_t ble_l2cap_lecb_disconnect(uint8_t conn_idx, uint16_t local_cid); 253 254 /** 255 **************************************************************************************** 256 * @brief Send a LE Flow Control Credit packet when the device is capable of receiving additional LE-frames 257 * (for example after the device has processed the sdu). 258 * 259 * @param[in] conn_idx: ACL connection index, the first ACL connection index is 0, and increased one by one. 260 * @param[in] p_add_credits: Pointer to the LE Flow Control Credit structure. 261 * 262 * @retval ::SDK_SUCCESS: LE Flow Control Credit packet is successfully set to the BLE stack. 263 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 264 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 265 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 266 **************************************************************************************** 267 */ 268 uint16_t ble_l2cap_lecb_credits_add(uint8_t conn_idx, const lecb_add_credits_t *p_add_credits); 269 270 /** 271 **************************************************************************************** 272 * @brief Send an SDU packet to the peer device. 273 * 274 * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0 and 275 * the index will be increased one by one. 276 * @param[in] p_sdu: Pointer to the sdu packet structure. 277 * 278 * @retval ::SDK_SUCCESS: The sdu packet is successfully set to the BLE stack. 279 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 280 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 281 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 282 **************************************************************************************** 283 */ 284 uint16_t ble_l2cap_lecb_sdu_send(uint8_t conn_idx, const lecb_sdu_t *p_sdu); 285 286 /** 287 **************************************************************************************** 288 * @brief Register the callback for the PSM. 289 * 290 * @param[in] le_psm: The le_psm number. 291 * @param[in] p_cb: Pointer to the callback structure. 292 * 293 * @retval ::SDK_SUCCESS: The callback is successfully registered to the BLE stack. 294 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 295 * @retval ::SDK_ERR_INVALID_PSM_EXCEEDED_MAX_PSM_NUM: The maximum PSM number limit is exceeded. 296 **************************************************************************************** 297 */ 298 uint16_t ble_l2cap_lecb_cb_register(uint16_t le_psm, const l2cap_lecb_cb_fun_t *p_cb); 299 300 /** @} */ 301 302 #endif 303 304 /** 305 @} 306 */ 307 /** @} */ 308