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