hci_api.h

00001 /*************************************************************************************************/
00002 /*!
00003  *  \file   hci_api.h
00004  *
00005  *  \brief  HCI subsystem API.
00006  *
00007  *          $Date: 2011-10-14 21:35:03 -0700 (Fri, 14 Oct 2011) $
00008  *          $Revision: 191 $
00009  *
00010  *  Copyright (c) 2009-2016 ARM Limited. All rights reserved.
00011  *
00012  *  SPDX-License-Identifier: LicenseRef-PBL
00013  *
00014  *  Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use
00015  *  this file except in compliance with the License.  You may obtain a copy of the License at
00016  *
00017  *  https://www.mbed.com/licenses/PBL-1.0
00018  *
00019  *  See the License for the specific language governing permissions and limitations under the License.
00020  */
00021 /*************************************************************************************************/
00022 #ifndef HCI_API_H
00023 #define HCI_API_H
00024 
00025 #include "wsf_types.h"
00026 #include "hci_defs.h"
00027 #include "wsf_os.h"
00028 #include "bda.h"
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 /**************************************************************************************************
00035   Macros
00036 **************************************************************************************************/
00037 
00038 /*! Internal event values for the HCI event and sec callbacks */
00039 #define HCI_RESET_SEQ_CMPL_CBACK_EVT                    0   /*! Reset sequence complete */
00040 #define HCI_LE_CONN_CMPL_CBACK_EVT                      1   /*! LE connection complete */
00041 #define HCI_DISCONNECT_CMPL_CBACK_EVT                   2   /*! LE disconnect complete */
00042 #define HCI_LE_CONN_UPDATE_CMPL_CBACK_EVT               3   /*! LE connection update complete */
00043 #define HCI_LE_CREATE_CONN_CANCEL_CMD_CMPL_CBACK_EVT    4   /*! LE create connection cancel command complete */
00044 #define HCI_LE_ADV_REPORT_CBACK_EVT                     5   /*! LE advertising report */
00045 #define HCI_READ_RSSI_CMD_CMPL_CBACK_EVT                6   /*! Read RSSI command complete */
00046 #define HCI_LE_READ_CHAN_MAP_CMD_CMPL_CBACK_EVT         7   /*! LE Read channel map command complete */
00047 #define HCI_READ_TX_PWR_LVL_CMD_CMPL_CBACK_EVT          8   /*! Read transmit power level command complete */
00048 #define HCI_READ_REMOTE_VER_INFO_CMPL_CBACK_EVT         9   /*! Read remote version information complete */
00049 #define HCI_LE_READ_REMOTE_FEAT_CMPL_CBACK_EVT          10  /*! LE read remote features complete */
00050 #define HCI_LE_LTK_REQ_REPL_CMD_CMPL_CBACK_EVT          11  /*! LE LTK request reply command complete */
00051 #define HCI_LE_LTK_REQ_NEG_REPL_CMD_CMPL_CBACK_EVT      12  /*! LE LTK request negative reply command complete */
00052 #define HCI_ENC_KEY_REFRESH_CMPL_CBACK_EVT              13  /*! Encryption key refresh complete */
00053 #define HCI_ENC_CHANGE_CBACK_EVT                        14  /*! Encryption change */
00054 #define HCI_LE_LTK_REQ_CBACK_EVT                        15  /*! LE LTK request */
00055 #define HCI_VENDOR_SPEC_CMD_STATUS_CBACK_EVT            16  /*! Vendor specific command status */
00056 #define HCI_VENDOR_SPEC_CMD_CMPL_CBACK_EVT              17  /*! Vendor specific command complete */
00057 #define HCI_VENDOR_SPEC_CBACK_EVT                       18  /*! Vendor specific */
00058 #define HCI_HW_ERROR_CBACK_EVT                          19  /*! Hardware error */
00059 #define HCI_LE_ENCRYPT_CMD_CMPL_CBACK_EVT               20  /*! LE encrypt command complete */
00060 #define HCI_LE_RAND_CMD_CMPL_CBACK_EVT                  21  /*! LE rand command complete */
00061 
00062 /**************************************************************************************************
00063   Data Types
00064 **************************************************************************************************/
00065 
00066 /*! Connection specification type */
00067 typedef struct
00068 {
00069   uint16_t            connIntervalMin;
00070   uint16_t            connIntervalMax;
00071   uint16_t            connLatency;
00072   uint16_t            supTimeout;
00073   uint16_t            minCeLen;
00074   uint16_t            maxCeLen;
00075 } hciConnSpec_t ;
00076 
00077 /*! LE connection complete event */
00078 typedef struct
00079 {
00080   wsfMsgHdr_t          hdr;
00081   uint8_t             status;
00082   uint16_t            handle;
00083   uint8_t             role;
00084   uint8_t             addrType;
00085   bdAddr_t             peerAddr;
00086   uint16_t            connInterval;
00087   uint16_t            connLatency;
00088   uint16_t            supTimeout;
00089   uint8_t             clockAccuracy;
00090 } hciLeConnCmplEvt_t ;
00091 
00092 /*! Disconnect complete event */
00093 typedef struct
00094 {
00095   wsfMsgHdr_t          hdr;
00096   uint8_t             status;
00097   uint16_t            handle;
00098   uint8_t             reason;
00099 } hciDisconnectCmplEvt_t ;
00100 
00101 /*! LE connection update complete event */
00102 typedef struct
00103 {
00104   wsfMsgHdr_t          hdr;
00105   uint8_t             status;
00106   uint16_t            handle;
00107   uint16_t            connInterval;
00108   uint16_t            connLatency;
00109   uint16_t            supTimeout;
00110 } hciLeConnUpdateCmplEvt_t ;
00111 
00112 /*! LE create connection cancel command complete event */
00113 typedef struct
00114 {
00115   wsfMsgHdr_t          hdr;
00116   uint8_t             status;
00117 } hciLeCreateConnCancelCmdCmplEvt_t ;
00118 
00119 /*! LE advertising report event */
00120 typedef struct
00121 {
00122   wsfMsgHdr_t          hdr;
00123   uint8_t             *pData;
00124   uint8_t             len;
00125   int8_t              rssi;
00126   uint8_t             eventType;
00127   uint8_t             addrType;
00128   bdAddr_t             addr;
00129 } hciLeAdvReportEvt_t ;
00130 
00131 /*! Read RSSI command complete event */
00132 typedef struct
00133 {
00134   wsfMsgHdr_t          hdr;
00135   uint8_t             status;
00136   uint8_t             handle;
00137   int8_t              rssi;
00138 } hciReadRssiCmdCmplEvt_t ;
00139 
00140 /*! LE Read channel map command complete event */
00141 typedef struct
00142 {
00143   wsfMsgHdr_t          hdr;
00144   uint8_t             status;
00145   uint16_t            handle;
00146   uint8_t             chanMap[HCI_CHAN_MAP_LEN];
00147 } hciReadChanMapCmdCmplEvt_t ;
00148 
00149 /*! Read transmit power level command complete event */
00150 typedef struct
00151 {
00152   wsfMsgHdr_t          hdr;
00153   uint8_t             status;
00154   uint8_t             handle;
00155   int8_t              pwrLvl;
00156 } hciReadTxPwrLvlCmdCmplEvt_t ;
00157 
00158 /*! Read remote version information complete event */
00159 typedef struct
00160 {
00161   wsfMsgHdr_t          hdr;
00162   uint8_t             status;
00163   uint16_t            handle;
00164   uint8_t             version;
00165   uint16_t            mfrName;
00166   uint16_t            subversion; 
00167 } hciReadRemoteVerInfoCmplEvt_t ;
00168 
00169 /*! LE read remote features complete event */
00170 typedef struct
00171 {
00172   wsfMsgHdr_t          hdr;
00173   uint8_t             status;
00174   uint16_t            handle;
00175   uint8_t             features[HCI_FEAT_LEN];
00176 } hciLeReadRemoteFeatCmplEvt_t ;
00177 
00178 /*! LE LTK request reply command complete event */
00179 typedef struct
00180 {
00181   wsfMsgHdr_t          hdr;
00182   uint8_t             status;
00183   uint16_t            handle;
00184 } hciLeLtkReqReplCmdCmplEvt_t ;
00185 
00186 /*! LE LTK request negative reply command complete event */
00187 typedef struct
00188 {
00189   wsfMsgHdr_t          hdr;
00190   uint8_t             status;
00191   uint16_t            handle;
00192 } hciLeLtkReqNegReplCmdCmplEvt_t ;
00193 
00194 /*! Encryption key refresh complete event */
00195 typedef struct
00196 {
00197   wsfMsgHdr_t          hdr;
00198   uint8_t             status;
00199   uint16_t            handle;
00200 } hciEncKeyRefreshCmpl_t ;
00201 
00202 /*! Encryption change event */
00203 typedef struct
00204 {
00205   wsfMsgHdr_t          hdr;
00206   uint8_t             status;
00207   uint16_t            handle;
00208   uint8_t             enabled;
00209 } hciEncChangeEvt_t ;
00210 
00211 /*! LE LTK request event */
00212 typedef struct
00213 {
00214   wsfMsgHdr_t          hdr;
00215   uint16_t            handle;
00216   uint8_t             randNum[HCI_RAND_LEN];
00217   uint16_t            encDiversifier;
00218 } hciLeLtkReqEvt_t ;
00219 
00220 /*! Vendor specific command status event */
00221 typedef struct
00222 {
00223   wsfMsgHdr_t         hdr;
00224   uint16_t           opcode;
00225 } hciVendorSpecCmdStatusEvt_t ;
00226 
00227 /*! Vendor specific command complete event */
00228 typedef struct
00229 {
00230   wsfMsgHdr_t         hdr;
00231   uint16_t           opcode;
00232   uint8_t            param[1];
00233 } hciVendorSpecCmdCmplEvt_t ;
00234 
00235 /*! Vendor specific event */
00236 typedef struct
00237 {
00238   wsfMsgHdr_t         hdr;
00239   uint8_t            param[1];
00240 } hciVendorSpecEvt_t ;
00241 
00242 /*! Hardware error event */
00243 typedef struct
00244 {
00245   wsfMsgHdr_t         hdr;
00246   uint8_t            code;
00247 } hciHwErrorEvt_t ;
00248 
00249 /*! LE encrypt command complete event */
00250 typedef struct
00251 {
00252   wsfMsgHdr_t         hdr;
00253   uint8_t            status;
00254   uint8_t            data[HCI_ENCRYPT_DATA_LEN];
00255 } hciLeEncryptCmdCmplEvt_t ;
00256 
00257 /*! LE rand command complete event */
00258 typedef struct
00259 {
00260   wsfMsgHdr_t         hdr;
00261   uint8_t            status;
00262   uint8_t            randNum[HCI_RAND_LEN];
00263 } hciLeRandCmdCmplEvt_t ;
00264 
00265 
00266 /*! Union of all event types */
00267 typedef union
00268 {
00269   wsfMsgHdr_t                        hdr;
00270   wsfMsgHdr_t                        resetSeqCmpl;
00271   hciLeConnCmplEvt_t                 leConnCmpl;
00272   hciDisconnectCmplEvt_t             disconnectCmpl;
00273   hciLeConnUpdateCmplEvt_t           leConnUpdateCmpl;
00274   hciLeCreateConnCancelCmdCmplEvt_t  leCreateConnCancelCmdCmpl;
00275   hciLeAdvReportEvt_t                leAdvReport;
00276   hciReadRssiCmdCmplEvt_t            readRssiCmdCmpl;
00277   hciReadChanMapCmdCmplEvt_t         readChanMapCmdCmpl;    
00278   hciReadTxPwrLvlCmdCmplEvt_t        readTxPwrLvlCmdCmpl;   
00279   hciReadRemoteVerInfoCmplEvt_t      readRemoteVerInfoCmpl;  
00280   hciLeReadRemoteFeatCmplEvt_t       leReadRemoteFeatCmpl;  
00281   hciLeLtkReqReplCmdCmplEvt_t        leLtkReqReplCmdCmpl;   
00282   hciLeLtkReqNegReplCmdCmplEvt_t     leLtkReqNegReplCmdCmpl;
00283   hciEncKeyRefreshCmpl_t             encKeyRefreshCmpl;       
00284   hciEncChangeEvt_t                  encChange;             
00285   hciLeLtkReqEvt_t                   leLtkReq;                 
00286   hciVendorSpecCmdStatusEvt_t        vendorSpecCmdStatus;   
00287   hciVendorSpecCmdCmplEvt_t          vendorSpecCmdCmpl;     
00288   hciVendorSpecEvt_t                 vendorSpec;            
00289   hciHwErrorEvt_t                    hwError;
00290   hciLeEncryptCmdCmplEvt_t           leEncryptCmdCmpl;
00291   hciLeRandCmdCmplEvt_t              leRandCmdCmpl;
00292 } hciEvt_t ;
00293 
00294 /**************************************************************************************************
00295   Callback Function Types
00296 **************************************************************************************************/
00297 
00298 typedef void (*hciEvtCback_t)(hciEvt_t  *pEvent);
00299 typedef void (*hciSecCback_t)(hciEvt_t  *pEvent);
00300 typedef void (*hciAclCback_t)(uint8_t *pData);
00301 typedef void (*hciFlowCback_t)(uint16_t handle, bool_t flowDisabled);
00302 
00303 /**************************************************************************************************
00304   Function Declarations
00305 **************************************************************************************************/
00306 
00307 /*! Initialization, registration, and reset */
00308 void HciEvtRegister (hciEvtCback_t evtCback);
00309 void HciSecRegister(hciSecCback_t secCback);
00310 void HciAclRegister(hciAclCback_t aclCback, hciFlowCback_t flowCback);
00311 void HciResetSequence(void);
00312 void HciVsInit(uint8_t param);
00313 
00314 /*! Optimization interface */
00315 uint8_t *HciGetBdAddr (void);
00316 uint8_t HciGetWhiteListSize(void);
00317 int8_t HciGetAdvTxPwr(void);
00318 uint16_t HciGetBufSize(void);
00319 uint8_t HciGetNumBufs(void);
00320 uint8_t *HciGetSupStates(void);
00321 uint8_t HciGetLeSupFeat(void);
00322 
00323 /*! ACL data interface */
00324 void HciSendAclData (uint8_t *pAclData);
00325 
00326 /*! Command interface */
00327 void HciDisconnectCmd (uint16_t handle, uint8_t reason);
00328 void HciLeAddDevWhiteListCmd(uint8_t addrType, uint8_t *pAddr);
00329 void HciLeClearWhiteListCmd(void);
00330 void HciLeConnUpdateCmd(uint16_t handle, hciConnSpec_t  *pConnSpec);
00331 void HciLeCreateConnCmd(uint16_t scanInterval, uint16_t scanWindow, uint8_t filterPolicy,
00332                         uint8_t peerAddrType, uint8_t *pPeerAddr, uint8_t ownAddrType,
00333                         hciConnSpec_t  *pConnSpec);
00334 void HciLeCreateConnCancelCmd(void);
00335 void HciLeEncryptCmd(uint8_t *pKey, uint8_t *pData);
00336 void HciLeLtkReqNegReplCmd(uint16_t handle);
00337 void HciLeLtkReqReplCmd(uint16_t handle, uint8_t *pKey);
00338 void HciLeRandCmd(void);
00339 void HciLeReadAdvTXPowerCmd(void);
00340 void HciLeReadBufSizeCmd(void);
00341 void HciLeReadChanMapCmd(uint16_t handle);
00342 void HciLeReadLocalSupFeatCmd(void);
00343 void HciLeReadRemoteFeatCmd(uint16_t handle);
00344 void HciLeReadSupStatesCmd(void);
00345 void HciLeReadWhiteListSizeCmd(void);
00346 void HciLeRemoveDevWhiteListCmd(uint8_t addrType, uint8_t *pAddr);
00347 void HciLeSetAdvEnableCmd(uint8_t enable);
00348 void HciLeSetAdvDataCmd(uint8_t len, uint8_t *pData);
00349 void HciLeSetAdvParamCmd(uint16_t advIntervalMin, uint16_t advIntervalMax, uint8_t advType,
00350                          uint8_t ownAddrType, uint8_t directAddrType, uint8_t *pDirectAddr,
00351                          uint8_t advChanMap, uint8_t advFiltPolicy);
00352 void HciLeSetEventMaskCmd(uint8_t *pLeEventMask);
00353 void HciLeSetHostChanClassCmd(uint8_t *pChanMap);
00354 void HciLeSetRandAddrCmd(uint8_t *pAddr);
00355 void HciLeSetScanEnableCmd(uint8_t enable, uint8_t filterDup);
00356 void HciLeSetScanParamCmd(uint8_t scanType, uint16_t scanInterval, uint16_t scanWindow,
00357                           uint8_t ownAddrType, uint8_t scanFiltPolicy);
00358 void HciLeSetScanRespDataCmd(uint8_t len, uint8_t *pData);
00359 void HciLeStartEncryptionCmd(uint16_t handle, uint8_t *pRand, uint16_t diversifier, uint8_t *pKey);
00360 void HciReadBdAddrCmd(void);
00361 void HciReadBufSizeCmd(void);
00362 void HciReadLocalSupFeatCmd(void);
00363 void HciReadLocalVerInfoCmd(void);
00364 void HciReadRemoteVerInfoCmd(uint16_t handle);
00365 void HciReadRssiCmd(uint16_t handle);
00366 void HciReadTxPwrLvlCmd(uint16_t handle, uint8_t type);
00367 void HciResetCmd(void);
00368 void HciSetEventMaskCmd(uint8_t *pEventMask);
00369 void HciVendorSpecificCmd(uint16_t opcode, uint8_t len, uint8_t *pData);
00370 
00371 #ifdef __cplusplus
00372 };
00373 #endif
00374 
00375 #endif /* HCI_API_H */