1 /****************************************************************************** 2 * 3 * Copyright 2018-2021 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 * \brief eSE debugging log Level 104 */ 105 extern bool ese_debug_enabled; 106 107 /** 108 * \ingroup spi_libese 109 * 110 * \brief This function is called by Jni/phNxpEse_open during the 111 * initialization of the ESE. It initializes protocol stack instance 112 * variables. 113 * 114 * \param[in] initParams - init parameters to be set while calling 115 * phNxpEse_init 116 * 117 * \retval This function return ESESTATUS_SUCCESS (0) in case of success 118 * In case of failure returns other failure value. 119 * 120 */ 121 ESESTATUS phNxpEse_init(phNxpEse_initParams initParams); 122 123 /** 124 * \ingroup spi_libese 125 * 126 * \brief Check if libese has opened 127 * 128 * \retval return false if it is close, otherwise true. 129 * 130 */ 131 bool phNxpEse_isOpen(); 132 133 /** 134 * \ingroup spi_libese 135 * 136 * \brief This function is used to communicate from nfc-hal to ese-hal 137 * 138 * \param[in] ioctlType - ioctl cmd 139 *\param[out] p_data - value read out 140 * 141 * \retval This function return ESESTATUS_SUCCESS (0) in case of success 142 * In case of failure returns other failure value. 143 * 144 */ 145 ESESTATUS phNxpEse_spiIoctl(uint64_t ioctlType, void* p_data); 146 /** 147 * \ingroup spi_libese 148 * 149 * \brief This function is called by hal interface api before any 150 * communication. It sets the end point variables 151 * 152 * \param[in] uEndPoint - select the end point type ( END_POINT_ESE = 0, 153 * END_POINT_eUICC =1 ). 154 * 155 * \retval This function return ESESTATUS_SUCCESS (0) in case of success 156 * In case of failure returns other failure value. 157 * 158 */ 159 ESESTATUS phNxpEse_SetEndPoint_Cntxt(uint8_t uEndPoint); 160 161 /** 162 * \ingroup spi_libese 163 * 164 * \brief This function is called by hal interface api before any 165 * communication. It resets the end point variables 166 * 167 * \param[in] uEndPoint - select the end point type ( END_POINT_ESE = 0, 168 * END_POINT_eUICC =1 ). 169 * 170 * \retval This function return ESESTATUS_SUCCESS (0) in case of success 171 * In case of failure returns other failure value. 172 * 173 */ 174 ESESTATUS phNxpEse_ResetEndPoint_Cntxt(uint8_t uEndPoint); 175 176 /** 177 * \ingroup spi_libese 178 * \brief This function is called by Jni during the 179 * initialization of the ESE. It opens the physical connection 180 * with ESE () and initializes the protocol stack 181 * 182 * \param[in] initParams - Initialize with init mode ( normal/osu) and media 183 * type(SPI- legacy/ APDU type). 184 * 185 * \retval ESESTATUS_SUCCESS On Success ESESTATUS_SUCCESS else proper error code 186 * 187 */ 188 ESESTATUS phNxpEse_open(phNxpEse_initParams initParams); 189 190 /** 191 * \ingroup spi_libese 192 * \brief This function is called by Jni during the 193 * initialization of the ESE. It opens the physical connection 194 * with ESE () and creates required client thread for 195 * operation. This will get priority access to ESE for timeout period. 196 * 197 * \param[in] initParams - Initialize with init mode ( normal/osu) and media 198 * type(SPI- legacy/ APDU type). 199 * 200 * \retval ESESTATUS_SUCCESS On Success ESESTATUS_SUCCESS else proper error code 201 * 202 */ 203 ESESTATUS phNxpEse_openPrioSession(phNxpEse_initParams initParams); 204 205 /** 206 * \ingroup spi_libese 207 * \brief This function prepares the C-APDU, send to ESE and then receives the 208 *response from ESE, 209 * decode it and returns data. 210 * 211 * \param[in] pCmd: Command to ESE 212 * \param[out] pRsp: Response from ESE (Returned data to be freed 213 *after copying) 214 * 215 * \retval ESESTATUS_SUCCESS On Success ESESTATUS_SUCCESS else proper error code 216 * 217 */ 218 219 ESESTATUS phNxpEse_Transceive(phNxpEse_data* pCmd, phNxpEse_data* pRsp); 220 221 /** 222 * \ingroup spi_libese 223 * 224 * \brief This function is called by Jni/phNxpEse_close during the 225 * de-initialization of the ESE. It de-initializes protocol stack 226 *instance variables 227 * 228 * \retval This function return ESESTATUS_SUCCESS (0) in case of success 229 * In case of failure returns other failure value. 230 * 231 */ 232 ESESTATUS phNxpEse_deInit(void); 233 234 /** 235 * \ingroup spi_libese 236 * \brief This function close the ESE interface and free all resources. 237 * 238 * 239 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 240 * 241 */ 242 243 ESESTATUS phNxpEse_close(ESESTATUS deInitStatus = ESESTATUS_SUCCESS); 244 245 /** 246 * \ingroup spi_libese 247 * \brief This function reset the ESE interface and free all 248 * 249 * 250 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 251 * 252 */ 253 ESESTATUS phNxpEse_reset(void); 254 255 /** 256 * \ingroup spi_libese 257 * \brief This function reset the ESE 258 * 259 * 260 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 261 * 262 */ 263 ESESTATUS phNxpEse_resetJcopUpdate(void); 264 265 /** 266 * \ingroup spi_libese 267 * \brief This function reset the P73 through ISO RST pin 268 * 269 * 270 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 271 * 272 */ 273 ESESTATUS phNxpEse_chipReset(void); 274 275 /** 276 * \ingroup spi_libese 277 * \brief This function is used to set IFSC size 278 * 279 * \param[in] IFS_Size 280 * 281 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 282 * 283 */ 284 ESESTATUS phNxpEse_setIfs(uint16_t IFS_Size); 285 286 /** 287 * \ingroup spi_libese 288 * \brief This function is used to get the ATR data from ESE 289 * 290 * \param[out] pATR 291 * 292 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 293 * 294 */ 295 ESESTATUS phNxpEse_getAtr(phNxpEse_data* pATR); 296 297 /** 298 * \ingroup spi_libese 299 * \brief This function sends the S-frame to indicate END_OF_APDU 300 * 301 * 302 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 303 * 304 */ 305 ESESTATUS phNxpEse_EndOfApdu(void); 306 307 /** 308 * \ingroup spi_libese 309 * \brief This function suspends execution of the calling thread for 310 * (at least) usec microseconds 311 * 312 * \param[in] usec 313 * 314 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 315 * 316 */ 317 ESESTATUS phNxpEse_Sleep(uint32_t usec); 318 319 /** 320 * \ingroup spi_libese 321 * \brief This function updates destination buffer with val 322 * data in len size 323 * 324 * \param[in] buff - Array to be updated 325 * \param[in] val - value to be updated 326 * \param[in] len - length of array to be updated 327 * 328 * \retval void 329 * 330 */ 331 void* phNxpEse_memset(void* buff, int val, size_t len); 332 333 /** 334 * \ingroup spi_libese 335 * \brief This function copies source buffer to destination buffer 336 * data in len size 337 * 338 * \param[in] dest - Destination array to be updated 339 * \param[in] src - Source array to be updated 340 * \param[in] len - length of array to be updated 341 * 342 * \retval void 343 * 344 */ 345 void* phNxpEse_memcpy(void* dest, const void* src, size_t len); 346 347 /** 348 * \ingroup spi_libese 349 * \brief This function suspends allocate memory 350 * 351 * \param[in] size 352 * 353 * \retval allocated memory. 354 * 355 */ 356 void* phNxpEse_memalloc(uint32_t size); 357 358 /** 359 * \ingroup spi_libese 360 * \brief This is utility function for runtime heap memory allocation 361 * 362 *\param[in] dataType - data type 363 * \param[in] size - number of bytes to be allocated 364 * 365 * \retval void 366 * 367 */ 368 void* phNxpEse_calloc(size_t dataType, size_t size); 369 370 /** 371 * \ingroup spi_libese 372 * \brief This is utility function for freeeing heap memory allocated 373 * 374 * \param[in] ptr - Address pointer to previous allocation 375 * 376 * \retval void 377 * 378 */ 379 void phNxpEse_free(void* ptr); 380 381 /** 382 * \ingroup spi_libese 383 * \brief This function performs disable/enable power control 384 * 385 * 386 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 387 * 388 */ 389 ESESTATUS phNxpEse_DisablePwrCntrl(void); 390 391 /** 392 * \ingroup spi_libese 393 * \brief This function is used to get the ESE timer status 394 * 395 * \param[out] timer_buffer 396 * 397 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 398 * 399 */ 400 ESESTATUS phNxpEse_GetEseStatus(phNxpEse_data* timer_buffer); 401 402 /** 403 * \ingroup spi_libese 404 * \brief This function power recycles the ESE 405 * (using prop. FW command) by talking to NFC HAL 406 * 407 * Note: 408 * After cold reset, phNxpEse_init need to be called to 409 * reset the host AP T=1 stack parameters 410 * 411 * 412 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 413 * 414 */ 415 ESESTATUS phNxpEse_coldReset(void); 416 417 /** 418 * \ingroup spi_libese 419 * \brief This function notifies SE hal service if it registers 420 * 421 * \param[out] state - WTX_ONGOIGN/WTX_END 422 * 423 * \retval void. 424 * 425 */ 426 void phNxpEse_NotifySEWtxRequest(phNxpEse_wtxState state); 427 428 /** 429 * \ingroup ISO7816-3_protocol_lib 430 * \brief This function is used to get OS mode(JCOP/OSU) 431 * 432 * \retval OS mode(JCOP/OSU). 433 * 434 */ 435 phNxpEseProto7816_OsType_t phNxpEse_GetOsMode(void); 436 437 /** 438 * \ingroup spi_libese 439 * \brief This function enable/disable resetprotection 440 * 441 * \param[in] flag - indicated enable or disable resetprotection. 442 * 443 * \retval ESESTATUS_SUCCESS Always return ESESTATUS_SUCCESS (0). 444 * 445 */ 446 ESESTATUS phNxpEse_doResetProtection(bool flag); 447 448 /** 449 * \ingroup spi_libese 450 * \brief This function is used to set the wtx count limit 451 * 452 * \param[in] wtxCount - value to set for wtx count limit 453 * 454 * \retval void. 455 * 456 */ 457 void phNxpEse_setWtxCountLimit(unsigned long int wtxCount); 458 /** @} */ 459 #endif /* _PHNXPSPILIB_API_H_ */ 460