1 /****************************************************************************** 2 * 3 * Copyright (C) 2009-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 /****************************************************************************** 20 * 21 * This interface file contains the interface to the Multi-Channel 22 * Adaptation Protocol (MCAP). 23 * 24 ******************************************************************************/ 25 #ifndef MCA_API_H 26 #define MCA_API_H 27 28 #include "bt_target.h" 29 #include "l2c_api.h" 30 31 /* move the following to bt_target.h or other place later */ 32 #define MCA_NUM_TC_TBL ((MCA_NUM_REGS)*(MCA_NUM_LINKS)*(MCA_NUM_MDLS+1)) 33 #define MCA_NUM_CCBS ((MCA_NUM_REGS)*(MCA_NUM_LINKS)) /* Number of control channel control blocks */ 34 #define MCA_NUM_DCBS ((MCA_NUM_REGS)*(MCA_NUM_LINKS)*(MCA_NUM_MDLS)) /* Number of data channel control blocks */ 35 36 37 /***************************************************************************** 38 ** constants 39 *****************************************************************************/ 40 /* API function return value result codes. */ 41 #define MCA_SUCCESS 0 /* Function successful */ 42 #define MCA_BAD_PARAMS 1 /* Invalid parameters */ 43 #define MCA_NO_RESOURCES 2 /* Not enough resources */ 44 #define MCA_BAD_HANDLE 3 /* Bad handle */ 45 #define MCA_BUSY 4 /* A procedure is already in progress */ 46 #define MCA_WRITE_FAIL 5 /* Write failed */ 47 #define MCA_BAD_MDL_ID 6 /* MDL ID is not valid for the current API */ 48 typedef UINT8 tMCA_RESULT; 49 50 /* MDEP data type. */ 51 #define MCA_TDEP_ECHO 0 /* MDEP for echo test */ 52 #define MCA_TDEP_DATA 1 /* MDEP for normal data */ 53 54 /* Control callback events. */ 55 #define MCA_ERROR_RSP_EVT 0 /* error response */ 56 #define MCA_CREATE_IND_EVT 1 /* create mdl indication */ 57 #define MCA_CREATE_CFM_EVT 2 /* create mdl confirm */ 58 #define MCA_RECONNECT_IND_EVT 3 /* reconnect mdl indication */ 59 #define MCA_RECONNECT_CFM_EVT 4 /* reconnect mdl confirm */ 60 #define MCA_ABORT_IND_EVT 5 /* abort mdl indication */ 61 #define MCA_ABORT_CFM_EVT 6 /* abort mdl confirm */ 62 #define MCA_DELETE_IND_EVT 7 /* delete mdl indication */ 63 #define MCA_DELETE_CFM_EVT 8 /* delete mdl confirm */ 64 65 #define MCA_SYNC_CAP_IND_EVT 0x11 /* request sync capabilities & requirements */ 66 #define MCA_SYNC_CAP_CFM_EVT 0x12 /* indicate completion */ 67 #define MCA_SYNC_SET_IND_EVT 0x13 /* request to set the time-stamp clock */ 68 #define MCA_SYNC_SET_CFM_EVT 0x14 /* indicate completion */ 69 #define MCA_SYNC_INFO_IND_EVT 0x15 /* update of the actual time-stamp clock instant from the sync slave */ 70 71 #define MCA_CONNECT_IND_EVT 0x20 /* Control channel connected */ 72 #define MCA_DISCONNECT_IND_EVT 0x21 /* Control channel disconnected */ 73 #define MCA_OPEN_IND_EVT 0x22 /* Data channel open indication */ 74 #define MCA_OPEN_CFM_EVT 0x23 /* Data channel open confirm */ 75 #define MCA_CLOSE_IND_EVT 0x24 /* Data channel close indication */ 76 #define MCA_CLOSE_CFM_EVT 0x25 /* Data channel close confirm */ 77 #define MCA_CONG_CHG_EVT 0x26 /* congestion change event */ 78 #define MCA_RSP_TOUT_IND_EVT 0x27 /* Control channel message response timeout */ 79 /***************************************************************************** 80 ** Type Definitions 81 *****************************************************************************/ 82 typedef UINT8 tMCA_HANDLE; /* the handle for registration. 1 based index to rcb */ 83 typedef UINT8 tMCA_CL; /* the handle for a control channel; reported at MCA_CONNECT_IND_EVT */ 84 typedef UINT8 tMCA_DEP; /* the handle for MCA_CreateDep. This is also the local mdep_id */ 85 typedef UINT16 tMCA_DL; /* the handle for the data channel. This is reported at MCA_OPEN_CFM_EVT or MCA_OPEN_IND_EVT */ 86 87 /* This is the data callback function. It is executed when MCAP has a data 88 ** packet ready for the application. 89 */ 90 typedef void (tMCA_DATA_CBACK)(tMCA_DL mdl, BT_HDR *p_pkt); 91 92 93 /* This structure contains parameters which are set at registration. */ 94 typedef struct { 95 UINT32 rsp_tout; /* MCAP signaling response timeout */ 96 UINT16 ctrl_psm; /* L2CAP PSM for the MCAP control channel */ 97 UINT16 data_psm; /* L2CAP PSM for the MCAP data channel */ 98 UINT16 sec_mask; /* Security mask for BTM_SetSecurityLevel() */ 99 } tMCA_REG; 100 101 /* This structure contains parameters to create a MDEP. */ 102 typedef struct { 103 UINT8 type; /* MCA_TDEP_DATA, or MCA_TDEP_ECHO. a regiatration may have only one MCA_TDEP_ECHO MDEP */ 104 UINT8 max_mdl; /* The maximum number of MDLs for this MDEP (max is MCA_NUM_MDLS) */ 105 tMCA_DATA_CBACK *p_data_cback; /* Data callback function */ 106 } tMCA_CS; 107 108 #define MCA_FCS_NONE 0 /* fcs_present=FALSE */ 109 #define MCA_FCS_BYPASS 0x10 /* fcs_present=TRUE, fcs=L2CAP_CFG_FCS_BYPASS */ 110 #define MCA_FCS_USE 0x11 /* fcs_present=TRUE, fcs=L2CAP_CFG_FCS_USE */ 111 #define MCA_FCS_PRESNT_MASK 0x10 /* fcs_present=TRUE */ 112 #define MCA_FCS_USE_MASK 0x01 /* mask for fcs */ 113 typedef UINT8 tMCA_FCS_OPT; 114 115 /* This structure contains L2CAP configuration parameters for the channel. */ 116 typedef struct { 117 tL2CAP_FCR_OPTS fcr_opt; 118 UINT8 user_rx_pool_id; 119 UINT8 user_tx_pool_id; 120 UINT8 fcr_rx_pool_id; 121 UINT8 fcr_tx_pool_id; 122 tMCA_FCS_OPT fcs; 123 UINT16 data_mtu; /* L2CAP MTU of the MCAP data channel */ 124 } tMCA_CHNL_CFG; 125 126 127 /* Header structure for callback event parameters. */ 128 typedef struct { 129 UINT16 mdl_id; /* The associated MDL ID */ 130 UINT8 op_code; /* The op (request/response) code */ 131 } tMCA_EVT_HDR; 132 133 /* Response Header structure for callback event parameters. */ 134 typedef struct { 135 UINT16 mdl_id; /* The associated MDL ID */ 136 UINT8 op_code; /* The op (request/response) code */ 137 UINT8 rsp_code; /* The response code */ 138 } tMCA_RSP_EVT; 139 140 /* This data structure is associated with the MCA_CREATE_IND_EVT. */ 141 typedef struct { 142 UINT16 mdl_id; /* The associated MDL ID */ 143 UINT8 op_code; /* The op (request/response) code */ 144 UINT8 dep_id; /* MDEP ID */ 145 UINT8 cfg; /* The configuration to negotiate */ 146 } tMCA_CREATE_IND; 147 148 /* This data structure is associated with the MCA_CREATE_CFM_EVT. */ 149 typedef struct { 150 UINT16 mdl_id; /* The associated MDL ID */ 151 UINT8 op_code; /* The op (request/response) code */ 152 UINT8 rsp_code; /* The response code. */ 153 UINT8 cfg; /* The configuration to negotiate */ 154 } tMCA_CREATE_CFM; 155 156 /* This data structure is associated with MCA_CONNECT_IND_EVT. */ 157 typedef struct { 158 BD_ADDR bd_addr; /* The peer address */ 159 UINT16 mtu; /* peer mtu */ 160 } tMCA_CONNECT_IND; 161 162 /* This data structure is associated with MCA_DISCONNECT_IND_EVT. */ 163 typedef struct { 164 BD_ADDR bd_addr; /* The peer address */ 165 UINT16 reason; /* disconnect reason given by L2CAP */ 166 } tMCA_DISCONNECT_IND; 167 168 /* This data structure is associated with MCA_OPEN_IND_EVT, and MCA_OPEN_CFM_EVT. */ 169 typedef struct { 170 UINT16 mdl_id; /* The associated MDL ID */ 171 tMCA_DL mdl; /* The handle for the data channel */ 172 UINT16 mtu; /* peer mtu */ 173 } tMCA_DL_OPEN; 174 175 /* This data structure is associated with MCA_CLOSE_IND_EVT and MCA_CLOSE_CFM_EVT. */ 176 typedef struct { 177 UINT16 mdl_id; /* The associated MDL ID */ 178 tMCA_DL mdl; /* The handle for the data channel */ 179 UINT16 reason; /* disconnect reason given by L2CAP */ 180 } tMCA_DL_CLOSE; 181 182 /* This data structure is associated with MCA_CONG_CHG_EVT. */ 183 typedef struct { 184 UINT16 mdl_id; /* N/A - This is a place holder */ 185 tMCA_DL mdl; /* The handle for the data channel */ 186 BOOLEAN cong; /* TRUE, if the channel is congested */ 187 } tMCA_CONG_CHG; 188 189 /* Union of all control callback event data structures */ 190 typedef union { 191 tMCA_EVT_HDR hdr; 192 tMCA_RSP_EVT rsp; 193 tMCA_CREATE_IND create_ind; 194 tMCA_CREATE_CFM create_cfm; 195 tMCA_EVT_HDR reconnect_ind; 196 tMCA_RSP_EVT reconnect_cfm; 197 tMCA_EVT_HDR abort_ind; 198 tMCA_RSP_EVT abort_cfm; 199 tMCA_EVT_HDR delete_ind; 200 tMCA_RSP_EVT delete_cfm; 201 tMCA_CONNECT_IND connect_ind; 202 tMCA_DISCONNECT_IND disconnect_ind; 203 tMCA_DL_OPEN open_ind; 204 tMCA_DL_OPEN open_cfm; 205 tMCA_DL_CLOSE close_ind; 206 tMCA_DL_CLOSE close_cfm; 207 tMCA_CONG_CHG cong_chg; 208 } tMCA_CTRL; 209 210 /* This is the control callback function. This function passes control events 211 ** to the application. 212 */ 213 typedef void (tMCA_CTRL_CBACK)(tMCA_HANDLE handle, tMCA_CL mcl, UINT8 event, 214 tMCA_CTRL *p_data); 215 216 217 /******************************************************************************* 218 ** 219 ** Function MCA_Init 220 ** 221 ** Description Initialize MCAP internal control blocks. 222 ** This function is called at stack start up. 223 ** 224 ** Returns void 225 ** 226 *******************************************************************************/ 227 MCA_API extern void MCA_Init(void); 228 229 /******************************************************************************* 230 ** 231 ** Function MCA_SetTraceLevel 232 ** 233 ** Description This function sets the debug trace level for MCA. 234 ** If 0xff is passed, the current trace level is returned. 235 ** 236 ** Input Parameters: 237 ** level: The level to set the MCA tracing to: 238 ** 0xff-returns the current setting. 239 ** 0-turns off tracing. 240 ** >= 1-Errors. 241 ** >= 2-Warnings. 242 ** >= 3-APIs. 243 ** >= 4-Events. 244 ** >= 5-Debug. 245 ** 246 ** Returns The new trace level or current trace level if 247 ** the input parameter is 0xff. 248 ** 249 *******************************************************************************/ 250 MCA_API extern UINT8 MCA_SetTraceLevel (UINT8 level); 251 252 /******************************************************************************* 253 ** 254 ** Function MCA_Register 255 ** 256 ** Description This function registers an MCAP implementation. 257 ** It is assumed that the control channel PSM and data channel 258 ** PSM are not used by any other instances of the stack. 259 ** If the given p_reg->ctrl_psm is 0, this handle is INT only. 260 ** 261 ** Returns 0, if failed. Otherwise, the MCA handle. 262 ** 263 *******************************************************************************/ 264 MCA_API extern tMCA_HANDLE MCA_Register(tMCA_REG *p_reg, tMCA_CTRL_CBACK *p_cback); 265 266 /******************************************************************************* 267 ** 268 ** Function MCA_Deregister 269 ** 270 ** Description This function is called to deregister an MCAP implementation. 271 ** Before this function can be called, all control and data 272 ** channels must be removed with MCA_DisconnectReq and MCA_CloseReq. 273 ** 274 ** Returns void 275 ** 276 *******************************************************************************/ 277 MCA_API extern void MCA_Deregister(tMCA_HANDLE handle); 278 279 /******************************************************************************* 280 ** 281 ** Function MCA_CreateDep 282 ** 283 ** Description Create a data endpoint. If the MDEP is created successfully, 284 ** the MDEP ID is returned in *p_dep. After a data endpoint is 285 ** created, an application can initiate a connection between this 286 ** endpoint and an endpoint on a peer device. 287 ** 288 ** Returns MCA_SUCCESS if successful, otherwise error. 289 ** 290 *******************************************************************************/ 291 MCA_API extern tMCA_RESULT MCA_CreateDep(tMCA_HANDLE handle, tMCA_DEP *p_dep, tMCA_CS *p_cs); 292 293 /******************************************************************************* 294 ** 295 ** Function MCA_DeleteDep 296 ** 297 ** Description Delete a data endpoint. This function is called when 298 ** the implementation is no longer using a data endpoint. 299 ** If this function is called when the endpoint is connected 300 ** the connection is closed and the data endpoint 301 ** is removed. 302 ** 303 ** Returns MCA_SUCCESS if successful, otherwise error. 304 ** 305 *******************************************************************************/ 306 MCA_API extern tMCA_RESULT MCA_DeleteDep(tMCA_HANDLE handle, tMCA_DEP dep); 307 308 /******************************************************************************* 309 ** 310 ** Function MCA_ConnectReq 311 ** 312 ** Description This function initiates an MCAP control channel connection 313 ** to the peer device. When the connection is completed, an 314 ** MCA_CONNECT_IND_EVT is reported to the application via its 315 ** control callback function. 316 ** This control channel is identified by tMCA_CL. 317 ** If the connection attempt fails, an MCA_DISCONNECT_IND_EVT is 318 ** reported. The security mask parameter overrides the outgoing 319 ** security mask set in MCA_Register(). 320 ** 321 ** Returns MCA_SUCCESS if successful, otherwise error. 322 ** 323 *******************************************************************************/ 324 MCA_API extern tMCA_RESULT MCA_ConnectReq(tMCA_HANDLE handle, BD_ADDR bd_addr, 325 UINT16 ctrl_psm, 326 UINT16 sec_mask); 327 328 /******************************************************************************* 329 ** 330 ** Function MCA_DisconnectReq 331 ** 332 ** Description This function disconnect an MCAP control channel 333 ** to the peer device. 334 ** If associated data channel exists, they are disconnected. 335 ** When the MCL is disconnected an MCA_DISCONNECT_IND_EVT is 336 ** reported to the application via its control callback function. 337 ** 338 ** Returns MCA_SUCCESS if successful, otherwise error. 339 ** 340 *******************************************************************************/ 341 MCA_API extern tMCA_RESULT MCA_DisconnectReq(tMCA_CL mcl); 342 343 /******************************************************************************* 344 ** 345 ** Function MCA_CreateMdl 346 ** 347 ** Description This function sends a CREATE_MDL request to the peer device. 348 ** When the response is received, a MCA_CREATE_CFM_EVT is reported 349 ** with the given MDL ID. 350 ** If the response is successful, a data channel is open 351 ** with the given p_chnl_cfg 352 ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT 353 ** is reported. This data channel is identified as tMCA_DL. 354 ** 355 ** Returns MCA_SUCCESS if successful, otherwise error. 356 ** 357 *******************************************************************************/ 358 MCA_API extern tMCA_RESULT MCA_CreateMdl(tMCA_CL mcl, tMCA_DEP dep, UINT16 data_psm, 359 UINT16 mdl_id, UINT8 peer_dep_id, 360 UINT8 cfg, const tMCA_CHNL_CFG *p_chnl_cfg); 361 362 /******************************************************************************* 363 ** 364 ** Function MCA_CreateMdlRsp 365 ** 366 ** Description This function sends a CREATE_MDL response to the peer device 367 ** in response to a received MCA_CREATE_IND_EVT. 368 ** If the rsp_code is successful, a data channel is open 369 ** with the given p_chnl_cfg 370 ** When the data channel is open successfully, a MCA_OPEN_IND_EVT 371 ** is reported. This data channel is identified as tMCA_DL. 372 ** 373 ** Returns MCA_SUCCESS if successful, otherwise error. 374 ** 375 *******************************************************************************/ 376 MCA_API extern tMCA_RESULT MCA_CreateMdlRsp(tMCA_CL mcl, tMCA_DEP dep, 377 UINT16 mdl_id, UINT8 cfg, UINT8 rsp_code, 378 const tMCA_CHNL_CFG *p_chnl_cfg); 379 380 /******************************************************************************* 381 ** 382 ** Function MCA_CloseReq 383 ** 384 ** Description Close a data channel. When the channel is closed, an 385 ** MCA_CLOSE_CFM_EVT is sent to the application via the 386 ** control callback function for this handle. 387 ** 388 ** Returns MCA_SUCCESS if successful, otherwise error. 389 ** 390 *******************************************************************************/ 391 MCA_API extern tMCA_RESULT MCA_CloseReq(tMCA_DL mdl); 392 393 /******************************************************************************* 394 ** 395 ** Function MCA_ReconnectMdl 396 ** 397 ** Description This function sends a RECONNECT_MDL request to the peer device. 398 ** When the response is received, a MCA_RECONNECT_CFM_EVT is reported. 399 ** If the response is successful, a data channel is open. 400 ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT 401 ** is reported. 402 ** 403 ** Returns MCA_SUCCESS if successful, otherwise error. 404 ** 405 *******************************************************************************/ 406 MCA_API extern tMCA_RESULT MCA_ReconnectMdl(tMCA_CL mcl, tMCA_DEP dep, UINT16 data_psm, 407 UINT16 mdl_id, const tMCA_CHNL_CFG *p_chnl_cfg); 408 409 /******************************************************************************* 410 ** 411 ** Function MCA_ReconnectMdlRsp 412 ** 413 ** Description This function sends a RECONNECT_MDL response to the peer device 414 ** in response to a MCA_RECONNECT_IND_EVT event. 415 ** If the response is successful, a data channel is open. 416 ** When the data channel is open successfully, a MCA_OPEN_IND_EVT 417 ** is reported. 418 ** 419 ** Returns MCA_SUCCESS if successful, otherwise error. 420 ** 421 *******************************************************************************/ 422 MCA_API extern tMCA_RESULT MCA_ReconnectMdlRsp(tMCA_CL mcl, tMCA_DEP dep, 423 UINT16 mdl_id, UINT8 rsp_code, 424 const tMCA_CHNL_CFG *p_chnl_cfg); 425 426 /******************************************************************************* 427 ** 428 ** Function MCA_DataChnlCfg 429 ** 430 ** Description This function initiates a data channel connection toward the 431 ** connected peer device. 432 ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT 433 ** is reported. This data channel is identified as tMCA_DL. 434 ** 435 ** Returns MCA_SUCCESS if successful, otherwise error. 436 ** 437 *******************************************************************************/ 438 MCA_API extern tMCA_RESULT MCA_DataChnlCfg(tMCA_CL mcl, const tMCA_CHNL_CFG *p_chnl_cfg); 439 440 /******************************************************************************* 441 ** 442 ** Function MCA_Abort 443 ** 444 ** Description This function sends a ABORT_MDL request to the peer device. 445 ** When the response is received, a MCA_ABORT_CFM_EVT is reported. 446 ** 447 ** Returns MCA_SUCCESS if successful, otherwise error. 448 ** 449 *******************************************************************************/ 450 MCA_API extern tMCA_RESULT MCA_Abort(tMCA_CL mcl); 451 452 /******************************************************************************* 453 ** 454 ** Function MCA_Delete 455 ** 456 ** Description This function sends a DELETE_MDL request to the peer device. 457 ** When the response is received, a MCA_DELETE_CFM_EVT is reported. 458 ** 459 ** Returns MCA_SUCCESS if successful, otherwise error. 460 ** 461 *******************************************************************************/ 462 MCA_API extern tMCA_RESULT MCA_Delete(tMCA_CL mcl, UINT16 mdl_id); 463 464 /******************************************************************************* 465 ** 466 ** Function MCA_WriteReq 467 ** 468 ** Description Send a data packet to the peer device. 469 ** 470 ** The application passes the packet using the BT_HDR structure. 471 ** The offset field must be equal to or greater than L2CAP_MIN_OFFSET. 472 ** This allows enough space in the buffer for the L2CAP header. 473 ** 474 ** The memory pointed to by p_pkt must be a GKI buffer 475 ** allocated by the application. This buffer will be freed 476 ** by the protocol stack; the application must not free 477 ** this buffer. 478 ** 479 ** Returns MCA_SUCCESS if successful, otherwise error. 480 ** 481 *******************************************************************************/ 482 MCA_API extern tMCA_RESULT MCA_WriteReq(tMCA_DL mdl, BT_HDR *p_pkt); 483 484 /******************************************************************************* 485 ** 486 ** Function MCA_GetL2CapChannel 487 ** 488 ** Description Get the L2CAP CID used by the given data channel handle. 489 ** 490 ** Returns L2CAP channel ID if successful, otherwise 0. 491 ** 492 *******************************************************************************/ 493 MCA_API extern UINT16 MCA_GetL2CapChannel (tMCA_DL mdl); 494 495 #endif /* MCA_API_H */ 496