nfa_ee_api.h revision 40e67c9ec7191cbda00cde97e4f988d1d5737762
1/****************************************************************************** 2 * 3 * Copyright (C) 2010-2014 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 * 22 * NFA interface to NFCEE 23 * 24 ******************************************************************************/ 25#ifndef NFA_EE_API_H 26#define NFA_EE_API_H 27 28#include "nfc_target.h" 29#include "nfa_api.h" 30#include "nfc_api.h" 31 32/***************************************************************************** 33** Constants and data types 34*****************************************************************************/ 35#define NFA_MAX_AID_LEN NFC_MAX_AID_LEN /* 16 per ISO 7816 specification */ 36#define NFA_EE_HANDLE_DH (NFA_HANDLE_GROUP_EE|NFC_DH_ID) 37 38/* NFA EE callback events */ 39enum 40{ 41 NFA_EE_DISCOVER_EVT, /* The status for NFA_EeDiscover () */ 42 NFA_EE_REGISTER_EVT, /* The status for NFA_EeRegister () */ 43 NFA_EE_DEREGISTER_EVT, /* The status for NFA_EeDeregister () */ 44 NFA_EE_MODE_SET_EVT, /* The status for activating or deactivating an NFCEE */ 45 NFA_EE_ADD_AID_EVT, /* The status for adding an AID to a routing table entry */ 46 NFA_EE_REMOVE_AID_EVT, /* The status for removing an AID from a routing table */ 47 NFA_EE_REMAINING_SIZE_EVT, /* The remaining size of the Listen Mode Routing Table */ 48 NFA_EE_SET_TECH_CFG_EVT, /* The status for setting the routing based on RF tech. */ 49 NFA_EE_SET_PROTO_CFG_EVT, /* The status for setting the routing based on protocols */ 50 NFA_EE_UPDATED_EVT, /* The status for NFA_EeUpdateNow */ 51 NFA_EE_CONNECT_EVT, /* Result of NFA_EeConnect */ 52 NFA_EE_DATA_EVT, /* Received data from NFCEE. */ 53 NFA_EE_DISCONNECT_EVT, /* NFCEE connection closed. */ 54 NFA_EE_NEW_EE_EVT, /* A new NFCEE is discovered */ 55 NFA_EE_ACTION_EVT, /* An action happened in NFCEE */ 56 NFA_EE_DISCOVER_REQ_EVT, /* NFCEE Discover Request Notification */ 57 NFA_EE_ROUT_ERR_EVT, /* Error - exceed NFCC CE Routing size */ 58 NFA_EE_NO_MEM_ERR_EVT, /* Error - out of GKI buffers */ 59 NFA_EE_NO_CB_ERR_EVT /* Error - Can not find control block or wrong state */ 60}; 61typedef UINT8 tNFA_EE_EVT; 62 63/* tNFA_NFCEE_INTERFACE values */ 64#define NFA_EE_INTERFACE_APDU NFC_NFCEE_INTERFACE_APDU /* APDU Interface */ 65#define NFA_EE_INTERFACE_HCI_ACCESS NFC_NFCEE_INTERFACE_HCI_ACCESS /* HCI Access Interface*/ 66#define NFA_EE_INTERFACE_T3T NFC_NFCEE_INTERFACE_T3T /* T3T Command Interface*/ 67#define NFA_EE_INTERFACE_TRANSPARENT NFC_NFCEE_INTERFACE_TRANSPARENT /* Transparent Interface*/ 68#define NFA_EE_INTERFACE_PROPRIETARY NFC_NFCEE_INTERFACE_PROPRIETARY /* Proprietary */ 69typedef UINT8 tNFA_EE_INTERFACE; 70 71#define NFA_EE_TAG_HW_ID NFC_NFCEE_TAG_HW_ID /* HW/Registration ID */ 72#define NFA_EE_TAG_ATR_BYTES NFC_NFCEE_TAG_ATR_BYTES /* ATR Bytes */ 73#define NFA_EE_TAG_T3T_INFO NFC_NFCEE_TAG_T3T_INFO /* T3T Supplement. Info */ 74#define NFA_EE_TAG_HCI_HOST_ID NFC_NFCEE_TAG_HCI_HOST_ID /* Broadcom Proprietary */ 75typedef UINT8 tNFA_EE_TAG; 76 77/* for NFA_EeModeSet () */ 78#define NFA_EE_MD_ACTIVATE NFC_MODE_ACTIVATE 79#define NFA_EE_MD_DEACTIVATE NFC_MODE_DEACTIVATE 80typedef UINT8 tNFA_EE_MD; 81 82#define NFA_EE_PWR_STATE_ON 0x01 /* The device is on */ 83#define NFA_EE_PWR_STATE_SWITCH_OFF 0x02 /* The device is switched off */ 84#define NFA_EE_PWR_STATE_BATT_OFF 0x04 /* The device's battery is removed */ 85#define NFA_EE_PWR_STATE_NONE 0 /* used to remove a particular technology or protocol based routing cfg of a handle from the routing table. */ 86typedef UINT8 tNFA_EE_PWR_STATE; 87 88 89#define NFA_EE_STATUS_INACTIVE NFC_NFCEE_STATUS_INACTIVE /* NFCEE connected and inactive */ 90#define NFA_EE_STATUS_ACTIVE NFC_NFCEE_STATUS_ACTIVE /* NFCEE connected and active */ 91#define NFA_EE_STATUS_REMOVED NFC_NFCEE_STATUS_REMOVED /* NFCEE removed */ 92#define NFA_EE_STATUS_PENDING 0x10 /* waiting for response from NFCC */ 93#define NFA_EE_STATUS_ACTIVATING (NFA_EE_STATUS_PENDING+NFC_NFCEE_STATUS_ACTIVE) 94#define NFA_EE_STATUS_DEACTIVATING (NFA_EE_STATUS_PENDING+NFC_NFCEE_STATUS_INACTIVE) 95typedef UINT8 tNFA_EE_STATUS; 96 97 98 99/* additional NFCEE Info */ 100typedef struct 101{ 102 tNFA_EE_TAG tag; 103 UINT8 len; 104 UINT8 info[NFC_MAX_EE_INFO]; 105} tNFA_EE_TLV; 106 107typedef struct 108{ 109 tNFA_HANDLE ee_handle; /* handle for NFCEE oe DH */ 110 tNFA_EE_STATUS ee_status; /* The NFCEE status */ 111 UINT8 num_interface; /* number of NFCEE interface*/ 112 tNFA_EE_INTERFACE ee_interface[NFC_MAX_EE_INTERFACE];/* NFCEE supported interface */ 113 UINT8 num_tlvs; /* number of TLVs */ 114 tNFA_EE_TLV ee_tlv[NFC_MAX_EE_TLVS];/* the TLV */ 115} tNFA_EE_INFO; 116 117 118 119typedef struct 120{ 121 tNFA_STATUS status; /* NFA_STATUS_OK is successful */ 122 UINT8 num_ee; /* number of NFCEEs found */ 123 tNFA_EE_INFO ee_info[NFA_EE_MAX_EE_SUPPORTED];/*NFCEE information */ 124} tNFA_EE_DISCOVER; 125 126typedef struct 127{ 128 tNFA_HANDLE ee_handle; /* Handle of NFCEE */ 129 tNFA_STATUS status; /* NFA_STATUS_OK is successful */ 130 tNFA_EE_INTERFACE ee_interface; /* NFCEE interface associated with this connection */ 131} tNFA_EE_CONNECT; 132 133#define NFA_EE_TRGR_SELECT NFC_EE_TRIG_SELECT /* ISO 7816-4 SELECT command */ 134#define NFA_EE_TRGR_RF_PROTOCOL NFC_EE_TRIG_RF_PROTOCOL /* RF Protocol changed */ 135#define NFA_EE_TRGR_RF_TECHNOLOGY NFC_EE_TRIG_RF_TECHNOLOGY/* RF Technology changed */ 136#define NFA_EE_TRGR_APP_INIT NFC_EE_TRIG_APP_INIT /* Application initiation */ 137typedef tNFC_EE_TRIGGER tNFA_EE_TRIGGER; 138 139/* Union of NFCEE action parameter depending on the associated trigger */ 140typedef union 141{ 142 tNFA_NFC_PROTOCOL protocol; /* NFA_EE_TRGR_RF_PROTOCOL: the protocol that triggers this event */ 143 tNFC_RF_TECH technology; /* NFA_EE_TRGR_RF_TECHNOLOGY:the technology that triggers this event */ 144 tNFC_AID aid; /* NFA_EE_TRGR_SELECT : the AID in the received SELECT AID command */ 145 tNFC_APP_INIT app_init; /* NFA_EE_TRGR_APP_INIT: The information for the application initiated trigger */ 146} tNFA_EE_ACTION_PARAM; 147 148typedef struct 149{ 150 tNFA_HANDLE ee_handle; /* Handle of NFCEE */ 151 tNFA_EE_TRIGGER trigger; /* the trigger of this event */ 152 tNFA_EE_ACTION_PARAM param; 153} tNFA_EE_ACTION; 154 155typedef struct 156{ 157 tNFA_HANDLE ee_handle; /* Handle of NFCEE */ 158 tNFA_STATUS status; /* NFA_STATUS_OK is successful */ 159 tNFA_EE_STATUS ee_status; /* The NFCEE status */ 160} tNFA_EE_MODE_SET; 161 162typedef struct 163{ 164 tNFA_HANDLE ee_handle; /* Handle of MFCEE */ 165 tNFA_NFC_PROTOCOL la_protocol; /* Listen A protocol */ 166 tNFA_NFC_PROTOCOL lb_protocol; /* Listen B protocol */ 167 tNFA_NFC_PROTOCOL lf_protocol; /* Listen F protocol */ 168 tNFA_NFC_PROTOCOL lbp_protocol; /* Listen B' protocol */ 169} tNFA_EE_DISCOVER_INFO; 170 171/* Data for NFA_EE_DISCOVER_REQ_EVT */ 172typedef struct 173{ 174 UINT8 status; /* NFA_STATUS_OK if successful */ 175 UINT8 num_ee; /* number of MFCEE information */ 176 tNFA_EE_DISCOVER_INFO ee_disc_info[NFA_EE_MAX_EE_SUPPORTED - 1]; /* NFCEE DISCOVER Request info */ 177} tNFA_EE_DISCOVER_REQ; 178 179/* Data for NFA_EE_DATA_EVT */ 180typedef struct 181{ 182 tNFA_HANDLE handle; /* Connection handle */ 183 UINT16 len; /* Length of data */ 184 UINT8 *p_buf; /* Data buffer */ 185} tNFA_EE_DATA; 186 187/* Union of all EE callback structures */ 188typedef union 189{ 190 tNFA_STATUS status; /* NFA_STATUS_OK is successful; otherwise NFA_STATUS_FAILED */ 191 tNFA_EE_DATA data; 192 tNFA_HANDLE handle; 193 tNFA_EE_DISCOVER ee_discover; 194 tNFA_STATUS ee_register; 195 tNFA_STATUS deregister; 196 tNFA_STATUS add_aid; 197 tNFA_STATUS remove_aid; 198 tNFA_STATUS set_tech; 199 tNFA_STATUS set_proto; 200 UINT16 size; 201 tNFA_EE_CONNECT connect; 202 tNFA_EE_ACTION action; 203 tNFA_EE_MODE_SET mode_set; 204 tNFA_EE_INFO new_ee; 205 tNFA_EE_DISCOVER_REQ discover_req; 206} tNFA_EE_CBACK_DATA; 207 208 209/* EE callback */ 210typedef void (tNFA_EE_CBACK) (tNFA_EE_EVT event, tNFA_EE_CBACK_DATA *p_data); 211 212/***************************************************************************** 213** External Function Declarations 214*****************************************************************************/ 215#ifdef __cplusplus 216extern "C" 217{ 218#endif 219 220/******************************************************************************* 221** 222** Function NFA_EeDiscover 223** 224** Description This function retrieves the NFCEE information from NFCC. 225** The NFCEE information is reported in NFA_EE_DISCOVER_EVT. 226** 227** This function may be called when a system supports removable 228** NFCEEs, 229** 230** Returns NFA_STATUS_OK if information is retrieved successfully 231** NFA_STATUS_FAILED If wrong state (retry later) 232** NFA_STATUS_INVALID_PARAM If bad parameter 233** 234*******************************************************************************/ 235NFC_API extern tNFA_STATUS NFA_EeDiscover (tNFA_EE_CBACK *p_cback); 236 237/******************************************************************************* 238** 239** Function NFA_EeGetInfo 240** 241** Description This function retrieves the NFCEE information from NFA. 242** The actual number of NFCEE is returned in p_num_nfcee 243** and NFCEE information is returned in p_info 244** 245** Returns NFA_STATUS_OK if information is retrieved successfully 246** NFA_STATUS_FAILED If wrong state (retry later) 247** NFA_STATUS_INVALID_PARAM If bad parameter 248** 249*******************************************************************************/ 250NFC_API extern tNFA_STATUS NFA_EeGetInfo (UINT8 *p_num_nfcee, 251 tNFA_EE_INFO *p_info); 252 253/******************************************************************************* 254** 255** Function NFA_EeRegister 256** 257** Description This function registers a callback function to receive the 258** events from NFA-EE module. 259** 260** Returns NFA_STATUS_OK if successfully initiated 261** NFA_STATUS_FAILED otherwise 262** NFA_STATUS_INVALID_PARAM If bad parameter 263** 264*******************************************************************************/ 265NFC_API extern tNFA_STATUS NFA_EeRegister (tNFA_EE_CBACK *p_cback); 266 267/******************************************************************************* 268** 269** Function NFA_EeDeregister 270** 271** Description This function de-registers the callback function 272** 273** Returns NFA_STATUS_OK if successfully initiated 274** NFA_STATUS_FAILED otherwise 275** NFA_STATUS_INVALID_PARAM If bad parameter 276** 277*******************************************************************************/ 278NFC_API extern tNFA_STATUS NFA_EeDeregister (tNFA_EE_CBACK *p_cback); 279 280/******************************************************************************* 281** 282** Function NFA_EeModeSet 283** 284** Description This function is called to activate (mode = NFA_EE_MD_ACTIVATE) 285** or deactivate (mode = NFA_EE_MD_DEACTIVATE) the NFCEE 286** identified by the given ee_handle. The result of this 287** operation is reported with the NFA_EE_MODE_SET_EVT. 288** 289** Returns NFA_STATUS_OK if successfully initiated 290** NFA_STATUS_FAILED otherwise 291** NFA_STATUS_INVALID_PARAM If bad parameter 292** 293*******************************************************************************/ 294NFC_API extern tNFA_STATUS NFA_EeModeSet (tNFA_HANDLE ee_handle, 295 tNFA_EE_MD mode); 296 297 298/******************************************************************************* 299** 300** Function NFA_EeSetDefaultTechRouting 301** 302** Description This function is called to add, change or remove the 303** default routing based on RF technology in the listen mode 304** routing table for the given ee_handle. The status of this 305** operation is reported as the NFA_EE_SET_TECH_CFG_EVT. 306** 307** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 308** should happen before calling this function 309** 310** Note: NFA_EeUpdateNow() should be called after last NFA-EE function 311** to change the listen mode routing is called. 312** 313** Returns NFA_STATUS_OK if successfully initiated 314** NFA_STATUS_FAILED otherwise 315** NFA_STATUS_INVALID_PARAM If bad parameter 316** 317*******************************************************************************/ 318NFC_API extern tNFA_STATUS NFA_EeSetDefaultTechRouting (tNFA_HANDLE ee_handle, 319 tNFA_TECHNOLOGY_MASK technologies_switch_on, 320 tNFA_TECHNOLOGY_MASK technologies_switch_off, 321 tNFA_TECHNOLOGY_MASK technologies_battery_off); 322 323/******************************************************************************* 324** 325** Function NFA_EeSetDefaultProtoRouting 326** 327** Description This function is called to add, change or remove the 328** default routing based on Protocol in the listen mode routing 329** table for the given ee_handle. The status of this 330** operation is reported as the NFA_EE_SET_PROTO_CFG_EVT. 331** 332** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 333** should happen before calling this function 334** 335** Note: NFA_EeUpdateNow() should be called after last NFA-EE function 336** to change the listen mode routing is called. 337** 338** Returns NFA_STATUS_OK if successfully initiated 339** NFA_STATUS_FAILED otherwise 340** NFA_STATUS_INVALID_PARAM If bad parameter 341** 342*******************************************************************************/ 343NFC_API extern tNFA_STATUS NFA_EeSetDefaultProtoRouting (tNFA_HANDLE ee_handle, 344 tNFA_PROTOCOL_MASK protocols_switch_on, 345 tNFA_PROTOCOL_MASK protocols_switch_off, 346 tNFA_PROTOCOL_MASK protocols_battery_off); 347 348/******************************************************************************* 349** 350** Function NFA_EeAddAidRouting 351** 352** Description This function is called to add an AID entry in the 353** listen mode routing table in NFCC. The status of this 354** operation is reported as the NFA_EE_ADD_AID_EVT. 355** 356** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 357** should happen before calling this function 358** 359** Note: NFA_EeUpdateNow() should be called after last NFA-EE function 360** to change the listen mode routing is called. 361** 362** Returns NFA_STATUS_OK if successfully initiated 363** NFA_STATUS_FAILED otherwise 364** NFA_STATUS_INVALID_PARAM If bad parameter 365** 366*******************************************************************************/ 367NFC_API extern tNFA_STATUS NFA_EeAddAidRouting (tNFA_HANDLE ee_handle, 368 UINT8 aid_len, 369 UINT8 *p_aid, 370 tNFA_EE_PWR_STATE power_state); 371 372/******************************************************************************* 373** 374** Function NFA_EeRemoveAidRouting 375** 376** Description This function is called to remove the given AID entry from the 377** listen mode routing table. If the entry configures VS, 378** it is also removed. The status of this operation is reported 379** as the NFA_EE_REMOVE_AID_EVT. 380** 381** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 382** should happen before calling this function 383** 384** Note: NFA_EeUpdateNow() should be called after last NFA-EE function 385** to change the listen mode routing is called. 386** 387** Returns NFA_STATUS_OK if successfully initiated 388** NFA_STATUS_FAILED otherwise 389** NFA_STATUS_INVALID_PARAM If bad parameter 390** 391*******************************************************************************/ 392NFC_API extern tNFA_STATUS NFA_EeRemoveAidRouting (UINT8 aid_len, 393 UINT8 *p_aid); 394 395/******************************************************************************* 396** 397** Function NFA_EeGetLmrtRemainingSize 398** 399** Description This function is called to get remaining size of the 400** Listen Mode Routing Table. 401** The remaining size is reported in NFA_EE_REMAINING_SIZE_EVT 402** 403** Returns NFA_STATUS_OK if successfully initiated 404** NFA_STATUS_FAILED otherwise 405** 406*******************************************************************************/ 407NFC_API extern tNFA_STATUS NFA_EeGetLmrtRemainingSize (void); 408 409/******************************************************************************* 410** 411** Function NFA_EeUpdateNow 412** 413** Description This function is called to send the current listen mode 414** routing table and VS configuration to the NFCC (without waiting 415** for NFA_EE_ROUT_TIMEOUT_VAL). 416** 417** The status of this operation is 418** reported with the NFA_EE_UPDATED_EVT. 419** 420** Returns NFA_STATUS_OK if successfully initiated 421** NFA_STATUS_SEMANTIC_ERROR is update is currently in progress 422** NFA_STATUS_FAILED otherwise 423** 424*******************************************************************************/ 425NFC_API extern tNFA_STATUS NFA_EeUpdateNow (void); 426 427/******************************************************************************* 428** 429** Function NFA_EeConnect 430** 431** Description Open connection to an NFCEE attached to the NFCC 432** 433** The status of this operation is 434** reported with the NFA_EE_CONNECT_EVT. 435** 436** Returns NFA_STATUS_OK if successfully initiated 437** NFA_STATUS_FAILED otherwise 438** NFA_STATUS_INVALID_PARAM If bad parameter 439** 440*******************************************************************************/ 441NFC_API extern tNFA_STATUS NFA_EeConnect (tNFA_HANDLE ee_handle, 442 UINT8 ee_interface, 443 tNFA_EE_CBACK *p_cback); 444 445/******************************************************************************* 446** 447** Function NFA_EeSendData 448** 449** Description Send data to the given NFCEE. 450** This function shall be called after NFA_EE_CONNECT_EVT is reported 451** and before NFA_EeDisconnect is called on the given ee_handle. 452** 453** Returns NFA_STATUS_OK if successfully initiated 454** NFA_STATUS_FAILED otherwise 455** NFA_STATUS_INVALID_PARAM If bad parameter 456** 457*******************************************************************************/ 458NFC_API extern tNFA_STATUS NFA_EeSendData (tNFA_HANDLE ee_handle, 459 UINT16 data_len, 460 UINT8 *p_data); 461 462/******************************************************************************* 463** 464** Function NFA_EeDisconnect 465** 466** Description Disconnect (if a connection is currently open) from an 467** NFCEE interface. The result of this operation is reported 468** with the NFA_EE_DISCONNECT_EVT. 469** 470** Returns NFA_STATUS_OK if successfully initiated 471** NFA_STATUS_FAILED otherwise 472** NFA_STATUS_INVALID_PARAM If bad parameter 473** 474*******************************************************************************/ 475NFC_API extern tNFA_STATUS NFA_EeDisconnect (tNFA_HANDLE ee_handle); 476 477 478#ifdef __cplusplus 479} 480#endif 481 482#endif /* NFA_EE_API_H */ 483 484