Home | History | Annotate | Download | only in include
      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