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