| /****************************************************************************** |
| * |
| * Copyright (C) 2009-2012 Broadcom Corporation |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at: |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| ******************************************************************************/ |
| |
| /****************************************************************************** |
| * |
| * This interface file contains the interface to the Multi-Channel |
| * Adaptation Protocol (MCAP). |
| * |
| ******************************************************************************/ |
| #ifndef MCA_API_H |
| #define MCA_API_H |
| |
| #include "bt_target.h" |
| #include "l2c_api.h" |
| |
| /* move the following to bt_target.h or other place later */ |
| #define MCA_NUM_TC_TBL ((MCA_NUM_REGS)*(MCA_NUM_LINKS)*(MCA_NUM_MDLS+1)) |
| #define MCA_NUM_CCBS ((MCA_NUM_REGS)*(MCA_NUM_LINKS)) /* Number of control channel control blocks */ |
| #define MCA_NUM_DCBS ((MCA_NUM_REGS)*(MCA_NUM_LINKS)*(MCA_NUM_MDLS)) /* Number of data channel control blocks */ |
| |
| |
| /***************************************************************************** |
| ** constants |
| *****************************************************************************/ |
| /* API function return value result codes. */ |
| #define MCA_SUCCESS 0 /* Function successful */ |
| #define MCA_BAD_PARAMS 1 /* Invalid parameters */ |
| #define MCA_NO_RESOURCES 2 /* Not enough resources */ |
| #define MCA_BAD_HANDLE 3 /* Bad handle */ |
| #define MCA_BUSY 4 /* A procedure is already in progress */ |
| #define MCA_WRITE_FAIL 5 /* Write failed */ |
| #define MCA_BAD_MDL_ID 6 /* MDL ID is not valid for the current API */ |
| typedef UINT8 tMCA_RESULT; |
| |
| /* MDEP data type. */ |
| #define MCA_TDEP_ECHO 0 /* MDEP for echo test */ |
| #define MCA_TDEP_DATA 1 /* MDEP for normal data */ |
| |
| /* Control callback events. */ |
| #define MCA_ERROR_RSP_EVT 0 /* error response */ |
| #define MCA_CREATE_IND_EVT 1 /* create mdl indication */ |
| #define MCA_CREATE_CFM_EVT 2 /* create mdl confirm */ |
| #define MCA_RECONNECT_IND_EVT 3 /* reconnect mdl indication */ |
| #define MCA_RECONNECT_CFM_EVT 4 /* reconnect mdl confirm */ |
| #define MCA_ABORT_IND_EVT 5 /* abort mdl indication */ |
| #define MCA_ABORT_CFM_EVT 6 /* abort mdl confirm */ |
| #define MCA_DELETE_IND_EVT 7 /* delete mdl indication */ |
| #define MCA_DELETE_CFM_EVT 8 /* delete mdl confirm */ |
| |
| #define MCA_SYNC_CAP_IND_EVT 0x11 /* request sync capabilities & requirements */ |
| #define MCA_SYNC_CAP_CFM_EVT 0x12 /* indicate completion */ |
| #define MCA_SYNC_SET_IND_EVT 0x13 /* request to set the time-stamp clock */ |
| #define MCA_SYNC_SET_CFM_EVT 0x14 /* indicate completion */ |
| #define MCA_SYNC_INFO_IND_EVT 0x15 /* update of the actual time-stamp clock instant from the sync slave */ |
| |
| #define MCA_CONNECT_IND_EVT 0x20 /* Control channel connected */ |
| #define MCA_DISCONNECT_IND_EVT 0x21 /* Control channel disconnected */ |
| #define MCA_OPEN_IND_EVT 0x22 /* Data channel open indication */ |
| #define MCA_OPEN_CFM_EVT 0x23 /* Data channel open confirm */ |
| #define MCA_CLOSE_IND_EVT 0x24 /* Data channel close indication */ |
| #define MCA_CLOSE_CFM_EVT 0x25 /* Data channel close confirm */ |
| #define MCA_CONG_CHG_EVT 0x26 /* congestion change event */ |
| #define MCA_RSP_TOUT_IND_EVT 0x27 /* Control channel message response timeout */ |
| /***************************************************************************** |
| ** Type Definitions |
| *****************************************************************************/ |
| typedef UINT8 tMCA_HANDLE; /* the handle for registration. 1 based index to rcb */ |
| typedef UINT8 tMCA_CL; /* the handle for a control channel; reported at MCA_CONNECT_IND_EVT */ |
| typedef UINT8 tMCA_DEP; /* the handle for MCA_CreateDep. This is also the local mdep_id */ |
| typedef UINT16 tMCA_DL; /* the handle for the data channel. This is reported at MCA_OPEN_CFM_EVT or MCA_OPEN_IND_EVT */ |
| |
| /* This is the data callback function. It is executed when MCAP has a data |
| ** packet ready for the application. |
| */ |
| typedef void (tMCA_DATA_CBACK)(tMCA_DL mdl, BT_HDR *p_pkt); |
| |
| |
| /* This structure contains parameters which are set at registration. */ |
| typedef struct { |
| UINT32 rsp_tout; /* MCAP signaling response timeout */ |
| UINT16 ctrl_psm; /* L2CAP PSM for the MCAP control channel */ |
| UINT16 data_psm; /* L2CAP PSM for the MCAP data channel */ |
| UINT16 sec_mask; /* Security mask for BTM_SetSecurityLevel() */ |
| } tMCA_REG; |
| |
| /* This structure contains parameters to create a MDEP. */ |
| typedef struct { |
| UINT8 type; /* MCA_TDEP_DATA, or MCA_TDEP_ECHO. a regiatration may have only one MCA_TDEP_ECHO MDEP */ |
| UINT8 max_mdl; /* The maximum number of MDLs for this MDEP (max is MCA_NUM_MDLS) */ |
| tMCA_DATA_CBACK *p_data_cback; /* Data callback function */ |
| } tMCA_CS; |
| |
| #define MCA_FCS_NONE 0 /* fcs_present=FALSE */ |
| #define MCA_FCS_BYPASS 0x10 /* fcs_present=TRUE, fcs=L2CAP_CFG_FCS_BYPASS */ |
| #define MCA_FCS_USE 0x11 /* fcs_present=TRUE, fcs=L2CAP_CFG_FCS_USE */ |
| #define MCA_FCS_PRESNT_MASK 0x10 /* fcs_present=TRUE */ |
| #define MCA_FCS_USE_MASK 0x01 /* mask for fcs */ |
| typedef UINT8 tMCA_FCS_OPT; |
| |
| /* This structure contains L2CAP configuration parameters for the channel. */ |
| typedef struct { |
| tL2CAP_FCR_OPTS fcr_opt; |
| UINT8 user_rx_pool_id; |
| UINT8 user_tx_pool_id; |
| UINT8 fcr_rx_pool_id; |
| UINT8 fcr_tx_pool_id; |
| tMCA_FCS_OPT fcs; |
| UINT16 data_mtu; /* L2CAP MTU of the MCAP data channel */ |
| } tMCA_CHNL_CFG; |
| |
| |
| /* Header structure for callback event parameters. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| UINT8 op_code; /* The op (request/response) code */ |
| } tMCA_EVT_HDR; |
| |
| /* Response Header structure for callback event parameters. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| UINT8 op_code; /* The op (request/response) code */ |
| UINT8 rsp_code; /* The response code */ |
| } tMCA_RSP_EVT; |
| |
| /* This data structure is associated with the MCA_CREATE_IND_EVT. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| UINT8 op_code; /* The op (request/response) code */ |
| UINT8 dep_id; /* MDEP ID */ |
| UINT8 cfg; /* The configuration to negotiate */ |
| } tMCA_CREATE_IND; |
| |
| /* This data structure is associated with the MCA_CREATE_CFM_EVT. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| UINT8 op_code; /* The op (request/response) code */ |
| UINT8 rsp_code; /* The response code. */ |
| UINT8 cfg; /* The configuration to negotiate */ |
| } tMCA_CREATE_CFM; |
| |
| /* This data structure is associated with MCA_CONNECT_IND_EVT. */ |
| typedef struct { |
| BD_ADDR bd_addr; /* The peer address */ |
| UINT16 mtu; /* peer mtu */ |
| } tMCA_CONNECT_IND; |
| |
| /* This data structure is associated with MCA_DISCONNECT_IND_EVT. */ |
| typedef struct { |
| BD_ADDR bd_addr; /* The peer address */ |
| UINT16 reason; /* disconnect reason given by L2CAP */ |
| } tMCA_DISCONNECT_IND; |
| |
| /* This data structure is associated with MCA_OPEN_IND_EVT, and MCA_OPEN_CFM_EVT. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| tMCA_DL mdl; /* The handle for the data channel */ |
| UINT16 mtu; /* peer mtu */ |
| } tMCA_DL_OPEN; |
| |
| /* This data structure is associated with MCA_CLOSE_IND_EVT and MCA_CLOSE_CFM_EVT. */ |
| typedef struct { |
| UINT16 mdl_id; /* The associated MDL ID */ |
| tMCA_DL mdl; /* The handle for the data channel */ |
| UINT16 reason; /* disconnect reason given by L2CAP */ |
| } tMCA_DL_CLOSE; |
| |
| /* This data structure is associated with MCA_CONG_CHG_EVT. */ |
| typedef struct { |
| UINT16 mdl_id; /* N/A - This is a place holder */ |
| tMCA_DL mdl; /* The handle for the data channel */ |
| BOOLEAN cong; /* TRUE, if the channel is congested */ |
| } tMCA_CONG_CHG; |
| |
| /* Union of all control callback event data structures */ |
| typedef union { |
| tMCA_EVT_HDR hdr; |
| tMCA_RSP_EVT rsp; |
| tMCA_CREATE_IND create_ind; |
| tMCA_CREATE_CFM create_cfm; |
| tMCA_EVT_HDR reconnect_ind; |
| tMCA_RSP_EVT reconnect_cfm; |
| tMCA_EVT_HDR abort_ind; |
| tMCA_RSP_EVT abort_cfm; |
| tMCA_EVT_HDR delete_ind; |
| tMCA_RSP_EVT delete_cfm; |
| tMCA_CONNECT_IND connect_ind; |
| tMCA_DISCONNECT_IND disconnect_ind; |
| tMCA_DL_OPEN open_ind; |
| tMCA_DL_OPEN open_cfm; |
| tMCA_DL_CLOSE close_ind; |
| tMCA_DL_CLOSE close_cfm; |
| tMCA_CONG_CHG cong_chg; |
| } tMCA_CTRL; |
| |
| /* This is the control callback function. This function passes control events |
| ** to the application. |
| */ |
| typedef void (tMCA_CTRL_CBACK)(tMCA_HANDLE handle, tMCA_CL mcl, UINT8 event, |
| tMCA_CTRL *p_data); |
| |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_Init |
| ** |
| ** Description Initialize MCAP internal control blocks. |
| ** This function is called at stack start up. |
| ** |
| ** Returns void |
| ** |
| *******************************************************************************/ |
| MCA_API extern void MCA_Init(void); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_SetTraceLevel |
| ** |
| ** Description This function sets the debug trace level for MCA. |
| ** If 0xff is passed, the current trace level is returned. |
| ** |
| ** Input Parameters: |
| ** level: The level to set the MCA tracing to: |
| ** 0xff-returns the current setting. |
| ** 0-turns off tracing. |
| ** >= 1-Errors. |
| ** >= 2-Warnings. |
| ** >= 3-APIs. |
| ** >= 4-Events. |
| ** >= 5-Debug. |
| ** |
| ** Returns The new trace level or current trace level if |
| ** the input parameter is 0xff. |
| ** |
| *******************************************************************************/ |
| MCA_API extern UINT8 MCA_SetTraceLevel (UINT8 level); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_Register |
| ** |
| ** Description This function registers an MCAP implementation. |
| ** It is assumed that the control channel PSM and data channel |
| ** PSM are not used by any other instances of the stack. |
| ** If the given p_reg->ctrl_psm is 0, this handle is INT only. |
| ** |
| ** Returns 0, if failed. Otherwise, the MCA handle. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_HANDLE MCA_Register(tMCA_REG *p_reg, tMCA_CTRL_CBACK *p_cback); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_Deregister |
| ** |
| ** Description This function is called to deregister an MCAP implementation. |
| ** Before this function can be called, all control and data |
| ** channels must be removed with MCA_DisconnectReq and MCA_CloseReq. |
| ** |
| ** Returns void |
| ** |
| *******************************************************************************/ |
| MCA_API extern void MCA_Deregister(tMCA_HANDLE handle); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_CreateDep |
| ** |
| ** Description Create a data endpoint. If the MDEP is created successfully, |
| ** the MDEP ID is returned in *p_dep. After a data endpoint is |
| ** created, an application can initiate a connection between this |
| ** endpoint and an endpoint on a peer device. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_CreateDep(tMCA_HANDLE handle, tMCA_DEP *p_dep, tMCA_CS *p_cs); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_DeleteDep |
| ** |
| ** Description Delete a data endpoint. This function is called when |
| ** the implementation is no longer using a data endpoint. |
| ** If this function is called when the endpoint is connected |
| ** the connection is closed and the data endpoint |
| ** is removed. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_DeleteDep(tMCA_HANDLE handle, tMCA_DEP dep); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_ConnectReq |
| ** |
| ** Description This function initiates an MCAP control channel connection |
| ** to the peer device. When the connection is completed, an |
| ** MCA_CONNECT_IND_EVT is reported to the application via its |
| ** control callback function. |
| ** This control channel is identified by tMCA_CL. |
| ** If the connection attempt fails, an MCA_DISCONNECT_IND_EVT is |
| ** reported. The security mask parameter overrides the outgoing |
| ** security mask set in MCA_Register(). |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_ConnectReq(tMCA_HANDLE handle, BD_ADDR bd_addr, |
| UINT16 ctrl_psm, |
| UINT16 sec_mask); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_DisconnectReq |
| ** |
| ** Description This function disconnect an MCAP control channel |
| ** to the peer device. |
| ** If associated data channel exists, they are disconnected. |
| ** When the MCL is disconnected an MCA_DISCONNECT_IND_EVT is |
| ** reported to the application via its control callback function. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_DisconnectReq(tMCA_CL mcl); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_CreateMdl |
| ** |
| ** Description This function sends a CREATE_MDL request to the peer device. |
| ** When the response is received, a MCA_CREATE_CFM_EVT is reported |
| ** with the given MDL ID. |
| ** If the response is successful, a data channel is open |
| ** with the given p_chnl_cfg |
| ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT |
| ** is reported. This data channel is identified as tMCA_DL. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_CreateMdl(tMCA_CL mcl, tMCA_DEP dep, UINT16 data_psm, |
| UINT16 mdl_id, UINT8 peer_dep_id, |
| UINT8 cfg, const tMCA_CHNL_CFG *p_chnl_cfg); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_CreateMdlRsp |
| ** |
| ** Description This function sends a CREATE_MDL response to the peer device |
| ** in response to a received MCA_CREATE_IND_EVT. |
| ** If the rsp_code is successful, a data channel is open |
| ** with the given p_chnl_cfg |
| ** When the data channel is open successfully, a MCA_OPEN_IND_EVT |
| ** is reported. This data channel is identified as tMCA_DL. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_CreateMdlRsp(tMCA_CL mcl, tMCA_DEP dep, |
| UINT16 mdl_id, UINT8 cfg, UINT8 rsp_code, |
| const tMCA_CHNL_CFG *p_chnl_cfg); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_CloseReq |
| ** |
| ** Description Close a data channel. When the channel is closed, an |
| ** MCA_CLOSE_CFM_EVT is sent to the application via the |
| ** control callback function for this handle. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_CloseReq(tMCA_DL mdl); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_ReconnectMdl |
| ** |
| ** Description This function sends a RECONNECT_MDL request to the peer device. |
| ** When the response is received, a MCA_RECONNECT_CFM_EVT is reported. |
| ** If the response is successful, a data channel is open. |
| ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT |
| ** is reported. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_ReconnectMdl(tMCA_CL mcl, tMCA_DEP dep, UINT16 data_psm, |
| UINT16 mdl_id, const tMCA_CHNL_CFG *p_chnl_cfg); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_ReconnectMdlRsp |
| ** |
| ** Description This function sends a RECONNECT_MDL response to the peer device |
| ** in response to a MCA_RECONNECT_IND_EVT event. |
| ** If the response is successful, a data channel is open. |
| ** When the data channel is open successfully, a MCA_OPEN_IND_EVT |
| ** is reported. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_ReconnectMdlRsp(tMCA_CL mcl, tMCA_DEP dep, |
| UINT16 mdl_id, UINT8 rsp_code, |
| const tMCA_CHNL_CFG *p_chnl_cfg); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_DataChnlCfg |
| ** |
| ** Description This function initiates a data channel connection toward the |
| ** connected peer device. |
| ** When the data channel is open successfully, a MCA_OPEN_CFM_EVT |
| ** is reported. This data channel is identified as tMCA_DL. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_DataChnlCfg(tMCA_CL mcl, const tMCA_CHNL_CFG *p_chnl_cfg); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_Abort |
| ** |
| ** Description This function sends a ABORT_MDL request to the peer device. |
| ** When the response is received, a MCA_ABORT_CFM_EVT is reported. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_Abort(tMCA_CL mcl); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_Delete |
| ** |
| ** Description This function sends a DELETE_MDL request to the peer device. |
| ** When the response is received, a MCA_DELETE_CFM_EVT is reported. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_Delete(tMCA_CL mcl, UINT16 mdl_id); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_WriteReq |
| ** |
| ** Description Send a data packet to the peer device. |
| ** |
| ** The application passes the packet using the BT_HDR structure. |
| ** The offset field must be equal to or greater than L2CAP_MIN_OFFSET. |
| ** This allows enough space in the buffer for the L2CAP header. |
| ** |
| ** The memory pointed to by p_pkt must be a GKI buffer |
| ** allocated by the application. This buffer will be freed |
| ** by the protocol stack; the application must not free |
| ** this buffer. |
| ** |
| ** Returns MCA_SUCCESS if successful, otherwise error. |
| ** |
| *******************************************************************************/ |
| MCA_API extern tMCA_RESULT MCA_WriteReq(tMCA_DL mdl, BT_HDR *p_pkt); |
| |
| /******************************************************************************* |
| ** |
| ** Function MCA_GetL2CapChannel |
| ** |
| ** Description Get the L2CAP CID used by the given data channel handle. |
| ** |
| ** Returns L2CAP channel ID if successful, otherwise 0. |
| ** |
| *******************************************************************************/ |
| MCA_API extern UINT16 MCA_GetL2CapChannel (tMCA_DL mdl); |
| |
| #endif /* MCA_API_H */ |
