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