• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      UINT16          user_rx_buf_size;
119      UINT16          user_tx_buf_size;
120      UINT16          fcr_rx_buf_size;
121      UINT16          fcr_tx_buf_size;
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  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  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  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  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  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  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  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  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  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  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  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  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  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  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  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  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  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  extern UINT16 MCA_GetL2CapChannel (tMCA_DL mdl);
494  
495  #endif /* MCA_API_H */
496