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 */ 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_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 }; 61 typedef 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 */ 69 typedef 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 */ 75 typedef 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 80 typedef 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. */ 86 typedef 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) 95 typedef UINT8 tNFA_EE_STATUS; 96 97 98 99 /* additional NFCEE Info */ 100 typedef struct 101 { 102 tNFA_EE_TAG tag; 103 UINT8 len; 104 UINT8 info[NFC_MAX_EE_INFO]; 105 } tNFA_EE_TLV; 106 107 typedef 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 119 typedef 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 126 typedef 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 */ 137 typedef tNFC_EE_TRIGGER tNFA_EE_TRIGGER; 138 139 /* Union of NFCEE action parameter depending on the associated trigger */ 140 typedef 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 148 typedef 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 155 typedef 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 162 typedef 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 */ 172 typedef 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 */ 180 typedef 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 */ 188 typedef 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 */ 210 typedef void (tNFA_EE_CBACK) (tNFA_EE_EVT event, tNFA_EE_CBACK_DATA *p_data); 211 212 /***************************************************************************** 213 ** External Function Declarations 214 *****************************************************************************/ 215 #ifdef __cplusplus 216 extern "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 *******************************************************************************/ 235 NFC_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 *******************************************************************************/ 250 NFC_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 *******************************************************************************/ 265 NFC_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 *******************************************************************************/ 278 NFC_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 *******************************************************************************/ 294 NFC_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 *******************************************************************************/ 318 NFC_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 *******************************************************************************/ 343 NFC_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 *******************************************************************************/ 367 NFC_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 *******************************************************************************/ 392 NFC_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 *******************************************************************************/ 407 NFC_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 *******************************************************************************/ 425 NFC_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 *******************************************************************************/ 441 NFC_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 *******************************************************************************/ 458 NFC_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 *******************************************************************************/ 475 NFC_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