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