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