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 */
39enum {
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};
65typedef 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
78typedef 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
88typedef 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
93typedef 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
104typedef 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)
118typedef uint8_t tNFA_EE_STATUS;
119
120/* additional NFCEE Info */
121typedef struct {
122  tNFA_EE_TAG tag;
123  uint8_t len;
124  uint8_t info[NFC_MAX_EE_INFO];
125} tNFA_EE_TLV;
126
127typedef 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
137typedef 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
143typedef 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
158typedef tNFC_EE_TRIGGER tNFA_EE_TRIGGER;
159
160/* Union of NFCEE action parameter depending on the associated trigger */
161typedef 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
172typedef 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
178typedef 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
184typedef 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 */
193typedef 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 */
201typedef 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 */
208typedef 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 */
229typedef void(tNFA_EE_CBACK)(tNFA_EE_EVT event, tNFA_EE_CBACK_DATA* p_data);
230
231/*****************************************************************************
232**  External Function Declarations
233*****************************************************************************/
234#ifdef __cplusplus
235extern "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*******************************************************************************/
253extern 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*******************************************************************************/
268extern 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*******************************************************************************/
282extern 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*******************************************************************************/
295extern 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*******************************************************************************/
312extern 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*******************************************************************************/
335extern 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*******************************************************************************/
361extern 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*******************************************************************************/
386extern 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                                       uint8_t aidInfo);
390
391/*******************************************************************************
392**
393** Function         NFA_EeRemoveAidRouting
394**
395** Description      This function is called to remove the given AID entry from
396**                  the listen mode routing table. If the entry configures VS,
397**                  it is also removed. The status of this operation is reported
398**                  as the NFA_EE_REMOVE_AID_EVT.
399**
400** Note:            If RF discovery is started,
401**                  NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT should
402**                  happen before calling this function
403**
404** Note:            NFA_EeUpdateNow() should be called after last NFA-EE
405**                  function to change the listen mode routing is called.
406**
407** Returns          NFA_STATUS_OK if successfully initiated
408**                  NFA_STATUS_FAILED otherwise
409**                  NFA_STATUS_INVALID_PARAM If bad parameter
410**
411*******************************************************************************/
412extern tNFA_STATUS NFA_EeRemoveAidRouting(uint8_t aid_len, uint8_t* p_aid);
413
414/*******************************************************************************
415**
416** Function         NFA_EeGetLmrtRemainingSize
417**
418** Description      This function is called to get remaining size of the
419**                  Listen Mode Routing Table.
420**                  The remaining size is reported in NFA_EE_REMAINING_SIZE_EVT
421**
422** Returns          NFA_STATUS_OK if successfully initiated
423**                  NFA_STATUS_FAILED otherwise
424**
425*******************************************************************************/
426extern tNFA_STATUS NFA_EeGetLmrtRemainingSize(void);
427
428/*******************************************************************************
429**
430** Function         NFA_EeUpdateNow
431**
432** Description      This function is called to send the current listen mode
433**                  routing table and VS configuration to the NFCC (without
434**                  waiting for NFA_EE_ROUT_TIMEOUT_VAL).
435**
436**                  The status of this operation is
437**                  reported with the NFA_EE_UPDATED_EVT.
438**
439** Returns          NFA_STATUS_OK if successfully initiated
440**                  NFA_STATUS_SEMANTIC_ERROR is update is currently in progress
441**                  NFA_STATUS_FAILED otherwise
442**
443*******************************************************************************/
444extern tNFA_STATUS NFA_EeUpdateNow(void);
445
446/*******************************************************************************
447**
448** Function         NFA_EeConnect
449**
450** Description      Open connection to an NFCEE attached to the NFCC
451**
452**                  The status of this operation is
453**                  reported with the NFA_EE_CONNECT_EVT.
454**
455** Returns          NFA_STATUS_OK if successfully initiated
456**                  NFA_STATUS_FAILED otherwise
457**                  NFA_STATUS_INVALID_PARAM If bad parameter
458**
459*******************************************************************************/
460extern tNFA_STATUS NFA_EeConnect(tNFA_HANDLE ee_handle, uint8_t ee_interface,
461                                 tNFA_EE_CBACK* p_cback);
462
463/*******************************************************************************
464**
465** Function         NFA_EeSendData
466**
467** Description      Send data to the given NFCEE.
468**                  This function shall be called after NFA_EE_CONNECT_EVT is
469**                  reported and before NFA_EeDisconnect is called on the given
470**                  ee_handle.
471**
472** Returns          NFA_STATUS_OK if successfully initiated
473**                  NFA_STATUS_FAILED otherwise
474**                  NFA_STATUS_INVALID_PARAM If bad parameter
475**
476*******************************************************************************/
477extern tNFA_STATUS NFA_EeSendData(tNFA_HANDLE ee_handle, uint16_t data_len,
478                                  uint8_t* p_data);
479
480/*******************************************************************************
481**
482** Function         NFA_EeDisconnect
483**
484** Description      Disconnect (if a connection is currently open) from an
485**                  NFCEE interface. The result of this operation is reported
486**                  with the NFA_EE_DISCONNECT_EVT.
487**
488** Returns          NFA_STATUS_OK if successfully initiated
489**                  NFA_STATUS_FAILED otherwise
490**                  NFA_STATUS_INVALID_PARAM If bad parameter
491**
492*******************************************************************************/
493extern tNFA_STATUS NFA_EeDisconnect(tNFA_HANDLE ee_handle);
494
495#ifdef __cplusplus
496}
497#endif
498
499#endif /* NFA_EE_API_H */
500