• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /******************************************************************************
2  *
3  *  Copyright 2018-2023 NXP
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  * \addtogroup spi_libese
21  * \brief ESE Lib layer interface to application
22  * @{ */
23 
24 #ifndef _PHNXPSPILIB_API_H_
25 #define _PHNXPSPILIB_API_H_
26 
27 #include <phEseStatus.h>
28 #include <phNxpEsePal.h>
29 
30 /**
31  * \ingroup spi_libese
32  * \brief Ese data buffer
33  *
34  */
35 typedef struct phNxpEse_data {
36   uint32_t len;    /*!< length of the buffer */
37   uint8_t* p_data; /*!< pointer to a buffer */
38 } phNxpEse_data;
39 
40 /**
41  * \ingroup spi_libese
42  * \brief Ese Channel mode
43  *
44  */
45 typedef enum {
46   ESE_MODE_NORMAL = 0, /*!< All wired transaction other OSU */
47   ESE_MODE_OSU         /*!< Jcop Os update mode */
48 } phNxpEse_initMode;
49 
50 /**
51  * \ingroup spi_libese
52  * \brief Ese logical interface  i.e. MediaType
53  *
54  */
55 typedef enum {
56   ESE_PROTOCOL_MEDIA_SPI = 0x08,          /*!< Media Type - SPI legacy  */
57   ESE_PROTOCOL_MEDIA_SPI_APDU_GATE = 0xD0 /*!Media Type - APDU Gate */
58 } phNxpEse_mediaType;
59 
60 typedef enum {
61   WTX_ONGOING = 1,
62   WTX_END = 2,
63 } phNxpEse_wtxState;
64 
65 typedef enum phNxpEseProto7816_OsType {
66   UNKNOWN_MODE = 0,
67   JCOP_MODE = 0x1,
68   OSU_MODE = 0x2,
69 } phNxpEseProto7816_OsType_t;
70 
71 #define MODE_JCOP 0x01
72 #define MODE_OSU 0x02
73 #define RESET_APP_WTX_COUNT 0
74 
75 typedef void(NotifyWtxReq)(phNxpEse_wtxState);
76 /**
77  * \ingroup spi_libese
78  * \brief Ese library init parameters to be set while calling phNxpEse_init
79  *
80  */
81 typedef struct phNxpEse_initParams {
82   phNxpEse_initMode initMode;   /*!< Ese communication mode */
83   phNxpEse_mediaType mediaType; /*!< Logical channel for Ese communication */
84   NotifyWtxReq* fPtr_WtxNtf;    /*!< Wait extension callback notification*/
85 } phNxpEse_initParams;
86 
87 /*!
88  * \brief SEAccess kit MW Android version
89  */
90 #define NXP_ANDROID_VER (9U)
91 
92 /*!
93  * \brief SEAccess kit MW Major version
94  */
95 #define ESELIB_MW_VERSION_MAJ (0x0U)
96 
97 /*!
98  * \brief SEAccess kit MW Minor version
99  */
100 #define ESELIB_MW_VERSION_MIN (0x04)
101 
102 /**
103  * \ingroup spi_libese
104  *
105  * \brief  This function is called by Jni/phNxpEse_open during the
106  *         initialization of the ESE. It initializes protocol stack instance
107  * variables.
108  *
109  * \param[in]    initParams - init parameters to be set while calling
110  * phNxpEse_init
111  *
112  * \retval This function return ESESTATUS_SUCCESS (0) in case of success
113  *         In case of failure returns other failure value.
114  *
115  */
116 ESESTATUS phNxpEse_init(phNxpEse_initParams initParams);
117 
118 #ifdef NXP_BOOTTIME_UPDATE
119 /**
120  * \ingroup spi_libese
121  *
122  * \brief  This function is used to communicate from nfc-hal to ese-hal
123  *
124  * \param[in]     ioctlType - ioctl cmd
125  *\param[out]    p_data - value read out
126  *
127  * \retval This function return ESESTATUS_SUCCESS (0) in case of success
128  *         In case of failure returns other failure value.
129  *
130  */
131 ESESTATUS phNxpEse_spiIoctl(uint64_t ioctlType, void* p_data);
132 #endif
133 
134 /**
135  * \ingroup spi_libese
136  *
137  * \brief  This function is called by hal interface api before any
138  *         communication. It sets the end point variables
139  *
140  *  \param[in]     uEndPoint - select the end point type (  END_POINT_ESE = 0,
141  * END_POINT_eUICC =1 ).
142  *
143  * \retval This function return ESESTATUS_SUCCESS (0) in case of success
144  *         In case of failure returns other failure value.
145  *
146  */
147 ESESTATUS phNxpEse_SetEndPoint_Cntxt(uint8_t uEndPoint);
148 
149 /**
150  * \ingroup spi_libese
151  *
152  * \brief  This function is called by hal interface api before any
153  *         communication. It resets the end point variables
154  *
155  * \param[in]     uEndPoint - select the end point type (  END_POINT_ESE = 0,
156  * END_POINT_eUICC =1 ).
157  *
158  * \retval This function return ESESTATUS_SUCCESS (0) in case of success
159  *         In case of failure returns other failure value.
160  *
161  */
162 ESESTATUS phNxpEse_ResetEndPoint_Cntxt(uint8_t uEndPoint);
163 
164 /**
165  * \ingroup spi_libese
166  * \brief This function is called by Jni during the
167  *        initialization of the ESE. It opens the physical connection
168  *        with ESE () and initializes the protocol stack
169  *
170  * \param[in]     initParams - Initialize with init mode ( normal/osu) and media
171  * type(SPI- legacy/ APDU type).
172  *
173  * \retval ESESTATUS_SUCCESS On Success ESESTATUS_SUCCESS else proper error code
174  *
175  */
176 ESESTATUS phNxpEse_open(phNxpEse_initParams initParams);
177 
178 /**
179  * \ingroup spi_libese
180  * \brief This function prepares the C-APDU, send to ESE and then receives the
181  *response from ESE,
182  *         decode it and returns data.
183  *
184  * \param[in]       pCmd: Command to ESE
185  * \param[out]     pRsp: Response from ESE (Returned data to be freed
186  *after copying)
187  *
188  * \retval ESESTATUS_SUCCESS On Success ESESTATUS_SUCCESS else proper error code
189  *
190  */
191 
192 ESESTATUS phNxpEse_Transceive(phNxpEse_data* pCmd, phNxpEse_data* pRsp);
193 
194 /**
195  * \ingroup spi_libese
196  *
197  * \brief  This function is called by Jni/phNxpEse_close during the
198  *         de-initialization of the ESE. It de-initializes protocol stack
199  *instance variables
200  *
201  * \retval This function return ESESTATUS_SUCCESS (0) in case of success
202  *         In case of failure returns other failure value.
203  *
204  */
205 ESESTATUS phNxpEse_deInit(void);
206 
207 /**
208  * \ingroup spi_libese
209  * \brief This function close the ESE interface and free all resources.
210  *
211  *
212  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
213  *
214  */
215 
216 ESESTATUS phNxpEse_close(ESESTATUS deInitStatus = ESESTATUS_SUCCESS);
217 
218 /**
219  * \ingroup spi_libese
220  * \brief This function reset the ESE interface and free all
221  *
222  *
223  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
224  *
225  */
226 ESESTATUS phNxpEse_reset(void);
227 
228 /**
229  * \ingroup spi_libese
230  * \brief This function reset the ESE
231  *
232  *
233  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
234  *
235  */
236 ESESTATUS phNxpEse_resetJcopUpdate(void);
237 
238 /**
239  * \ingroup spi_libese
240  * \brief This function reset the P73 through ISO RST pin
241  *
242  *
243  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
244  *
245  */
246 ESESTATUS phNxpEse_chipReset(void);
247 
248 /**
249  * \ingroup spi_libese
250  * \brief This function is used to set IFSC size
251  *
252  * \param[in]       IFS_Size
253  *
254  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
255  *
256  */
257 ESESTATUS phNxpEse_setIfs(uint16_t IFS_Size);
258 
259 /**
260  * \ingroup spi_libese
261  * \brief This function is used to get the ATR data from ESE
262  *
263  * \param[out]      pATR
264  *
265  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
266  *
267  */
268 ESESTATUS phNxpEse_getAtr(phNxpEse_data* pATR);
269 
270 /**
271  * \ingroup spi_libese
272  * \brief This function  suspends execution of the calling thread for
273  *           (at least) usec microseconds
274  *
275  * \param[in]       usec
276  *
277  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
278  *
279  */
280 ESESTATUS phNxpEse_Sleep(uint32_t usec);
281 
282 /**
283  * \ingroup spi_libese
284  * \brief This function updates destination buffer with val
285  *                 data in len size
286  *
287  * \param[in]    buff                - Array to be updated
288  * \param[in]    val                 - value to be updated
289  * \param[in]    len                 - length of array to be updated
290  *
291  * \retval   void
292  *
293  */
294 void* phNxpEse_memset(void* buff, int val, size_t len);
295 
296 /**
297  * \ingroup spi_libese
298  * \brief This function copies source buffer to  destination buffer
299  *                 data in len size
300  *
301  * \param[in]    dest                - Destination array to be updated
302  * \param[in]    src                 - Source array to be updated
303  * \param[in]    len                 - length of array to be updated
304  *
305  * \retval   void
306  *
307  */
308 void* phNxpEse_memcpy(void* dest, const void* src, size_t len);
309 
310 /**
311  * \ingroup spi_libese
312  * \brief This function  suspends allocate memory
313  *
314  * \param[in]       size
315  *
316  * \retval allocated memory.
317  *
318  */
319 void* phNxpEse_memalloc(uint32_t size);
320 
321 /**
322  * \ingroup spi_libese
323  * \brief This is utility function for runtime heap memory allocation
324  *
325  *\param[in]     dataType          - data type
326  * \param[in]    size                 - number of bytes to be allocated
327  *
328  * \retval   void
329  *
330  */
331 void* phNxpEse_calloc(size_t dataType, size_t size);
332 
333 /**
334  * \ingroup spi_libese
335  * \brief This is utility function for freeeing heap memory allocated
336  *
337  * \param[in]    ptr                 - Address pointer to previous allocation
338  *
339  * \retval   void
340  *
341  */
342 void phNxpEse_free(void* ptr);
343 
344 /**
345  * \ingroup spi_libese
346  * \brief This function power recycles the ESE
347  *        (using prop. FW command) by talking to NFC HAL
348  *
349  *        Note:
350  *        After cold reset, phNxpEse_init need to be called to
351  *        reset the host AP T=1 stack parameters
352  *
353  *
354  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
355  *
356  */
357 ESESTATUS phNxpEse_coldReset(void);
358 
359 /**
360  * \ingroup spi_libese
361  * \brief  This function notifies SE hal service if it registers
362  *
363  * \param[out]       state - WTX_ONGOIGN/WTX_END
364  *
365  * \retval void.
366  *
367  */
368 void phNxpEse_NotifySEWtxRequest(phNxpEse_wtxState state);
369 
370 /**
371  * \ingroup ISO7816-3_protocol_lib
372  * \brief This function is used to get OS mode(JCOP/OSU)
373  *
374  * \retval OS mode(JCOP/OSU).
375  *
376  */
377 phNxpEseProto7816_OsType_t phNxpEse_GetOsMode(void);
378 
379 /**
380  * \ingroup spi_libese
381  * \brief This function enable/disable resetprotection
382  *
383  * \param[in]    flag   - indicated enable or disable resetprotection.
384  *
385  * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0).
386  *
387  */
388 ESESTATUS phNxpEse_doResetProtection(bool flag);
389 
390 /**
391  * \ingroup spi_libese
392  * \brief This function is used to set the wtx count limit
393  *
394  * \param[in]    wtxCount     - value to set for wtx count limit
395  *
396  * \retval void.
397  *
398  */
399 void phNxpEse_setWtxCountLimit(unsigned long int wtxCount);
400 
401 /**
402  * \ingroup spi_libese
403  * \brief This function returns whether priority channel enabled or
404  *  not
405  *
406  * \param[in] void
407  *
408  * \retval uint8_t - Priority Access enabled(1)/disabled(0).
409  *
410  */
411 bool phNxpEse_isPriorityAccessEnabled(void);
412 
413 /** @} */
414 #endif /* _PHNXPSPILIB_API_H_ */
415