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 */ 48typedef 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*****************************************************************************/ 82typedef UINT8 tMCA_HANDLE; /* the handle for registration. 1 based index to rcb */ 83typedef UINT8 tMCA_CL; /* the handle for a control channel; reported at MCA_CONNECT_IND_EVT */ 84typedef UINT8 tMCA_DEP; /* the handle for MCA_CreateDep. This is also the local mdep_id */ 85typedef 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*/ 90typedef void (tMCA_DATA_CBACK)(tMCA_DL mdl, BT_HDR *p_pkt); 91 92 93/* This structure contains parameters which are set at registration. */ 94typedef 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. */ 102typedef 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 */ 113typedef UINT8 tMCA_FCS_OPT; 114 115/* This structure contains L2CAP configuration parameters for the channel. */ 116typedef 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. */ 128typedef 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. */ 134typedef 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. */ 141typedef 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. */ 149typedef 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. */ 157typedef 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. */ 163typedef 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. */ 169typedef 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. */ 176typedef 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. */ 183typedef 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 */ 190typedef 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*/ 213typedef 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*******************************************************************************/ 227MCA_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*******************************************************************************/ 250MCA_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*******************************************************************************/ 264MCA_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*******************************************************************************/ 277MCA_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*******************************************************************************/ 291MCA_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*******************************************************************************/ 306MCA_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*******************************************************************************/ 324MCA_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*******************************************************************************/ 341MCA_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*******************************************************************************/ 358MCA_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*******************************************************************************/ 376MCA_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*******************************************************************************/ 391MCA_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*******************************************************************************/ 406MCA_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*******************************************************************************/ 422MCA_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*******************************************************************************/ 438MCA_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*******************************************************************************/ 450MCA_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*******************************************************************************/ 462MCA_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*******************************************************************************/ 482MCA_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*******************************************************************************/ 493MCA_API extern UINT16 MCA_GetL2CapChannel (tMCA_DL mdl); 494 495#endif /* MCA_API_H */ 496