1 /****************************************************************************** 2 * 3 * Copyright 2018-2022 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 eSe_PAL 21 * \brief PAL implementation 22 * @{ */ 23 24 #ifndef _PHNXPESE_PAL_H 25 #define _PHNXPESE_PAL_H 26 27 /* Basic type definitions */ 28 #include <NxpTimer.h> 29 #include <errno.h> 30 #include <phEseStatus.h> 31 #include <phNxpEseFeatures.h> 32 #include <stdint.h> 33 /*! 34 * \brief Value indicates to reset device 35 */ 36 #define PH_PALESE_RESETDEVICE (0x00008001) 37 38 /*! 39 * \ingroup eSe_PAL 40 * 41 * \brief Enum definition contains supported ioctl control codes. 42 * 43 * phPalEse_IoCtl 44 */ 45 typedef enum { 46 phPalEse_e_Invalid = 0, /*!< Invalid control code */ 47 phPalEse_e_ResetDevice = PH_PALESE_RESETDEVICE, /*!< Reset the device */ 48 phPalEse_e_EnableLog, /*!< Enable the spi driver logs */ 49 phPalEse_e_EnablePollMode, /*!< Enable the polling for SPI */ 50 phPalEse_e_GetEseAccess, /*!< get the bus access in specified timeout */ 51 phPalEse_e_ChipRst, /*!< eSE Chip reset using ISO RST pin*/ 52 phPalEse_e_EnableThroughputMeasurement, /*!< Enable throughput measurement */ 53 phPalEse_e_SetPowerScheme, /*!< Set power scheme */ 54 phPalEse_e_GetSPMStatus, /*!< Get SPM(power mgt) status */ 55 phPalEse_e_DisablePwrCntrl, 56 phPalEse_e_SetJcopDwnldState, /*!< Set Jcop Download state */ 57 phPalEse_e_SetClientUpdateState, /*!< Set Jcop Download state */ 58 phPalEse_e_SetSecureMode, /*!< Set the Trusted SE Mode */ 59 phPalEse_e_ResetProtection, 60 } phPalEse_ControlCode_t; /*!< Control code for IOCTL call */ 61 62 /*! 63 * \ingroup eSe_PAL 64 * 65 * \brief PAL Configuration exposed to upper layer. 66 */ 67 typedef struct phPalEse_Config { 68 int8_t* pDevName; 69 /*!< Port name connected to ESE 70 * 71 * Platform specific canonical device name to which ESE is connected. 72 * 73 * e.g. On Linux based systems this would be /dev/p73 74 */ 75 76 uint32_t dwBaudRate; 77 /*!< Communication speed between DH and ESE 78 * 79 * This is the baudrate of the bus for communication between DH and ESE 80 */ 81 82 void* pDevHandle; 83 /*!< Device handle output */ 84 } phPalEse_Config_t, *pphPalEse_Config_t; /* pointer to phPalEse_Config_t */ 85 86 /*! 87 * \ingroup eSe_PAL 88 * 89 * \brief NxpTimer struct to measure cmd TX and response RX time. 90 */ 91 typedef struct phPalEse_NxpTimer { 92 NxpTimer* tx_timer; 93 /*!< timer to capture time taken for cmd transfer 94 */ 95 96 NxpTimer* rx_timer; 97 /*!< timer to capture time taken for response receival 98 */ 99 100 bool is_enabled; 101 /*!< TRUE if KPI measurement is enabled else FALSE 102 */ 103 104 } phPalEse_NxpTimer_t; 105 106 /* Function declarations */ 107 /** 108 * \ingroup eSe_PAL 109 * \brief This function is used to close the ESE device 110 * 111 * \retval None 112 * 113 */ 114 void phPalEse_close(void* pDevHandle); 115 116 /** 117 * \ingroup eSe_PAL 118 * \brief Open and configure ESE device 119 * 120 * \param[in] pConfig: Config to open the device 121 * 122 * \retval ESESTATUS On Success ESESTATUS_SUCCESS else proper error code 123 * 124 */ 125 ESESTATUS phPalEse_open_and_configure(pphPalEse_Config_t pConfig); 126 127 /** 128 * \ingroup eSe_PAL 129 * \brief ConfigTransport to get SPI terminal 130 * 131 * \retval ESESTATUS On Success ESESTATUS_SUCCESS else proper error code 132 * 133 */ 134 ESESTATUS phPalEse_ConfigTransport(); 135 136 /** 137 * \ingroup eSe_PAL 138 * \brief Reads requested number of bytes from ESE into given buffer 139 * 140 * \param[in] pDevHandle - valid device handle 141 **\param[in] pBuffer - buffer for read data 142 **\param[in] nNbBytesToRead - number of bytes requested to be read 143 * 144 * \retval numRead - number of successfully read bytes. 145 * \retval -1 - read operation failure 146 * 147 */ 148 int phPalEse_read(void* pDevHandle, uint8_t* pBuffer, int nNbBytesToRead); 149 150 /** 151 * \ingroup eSe_PAL 152 * \brief Writes requested number of bytes from given buffer into pn547 device 153 * 154 * \param[in] pDevHandle - valid device handle 155 * \param[in] pBuffer - buffer to write 156 * \param[in] nNbBytesToWrite - number of bytes to write 157 * 158 * \retval numWrote - number of successfully written bytes 159 * \retval -1 - write operation failure 160 * 161 */ 162 int phPalEse_write(void* pDevHandle, uint8_t* pBuffer, int nNbBytesToWrite); 163 164 /** 165 * \ingroup eSe_PAL 166 * \brief Exposed ioctl by ESE driver 167 * 168 * \param[in] eControlCode - phPalEse_ControlCode_t for the respective 169 *configs 170 * \param[in] pDevHandle - valid device handle 171 * \param[in] level - reset level 172 * 173 * \retval 0 - ioctl operation success 174 * \retval -1 - ioctl operation failure 175 * 176 */ 177 ESESTATUS phPalEse_ioctl(phPalEse_ControlCode_t eControlCode, void* pDevHandle, 178 long level); 179 180 /** 181 * \ingroup eSe_PAL 182 * \brief Print packet data 183 * 184 * \param[in] pString - String to be printed 185 * \param[in] p_data - data to be printed 186 * \param[in] len - Length of data to be printed 187 * 188 * \retval void 189 * 190 */ 191 void phPalEse_print_packet(const char* pString, const uint8_t* p_data, 192 uint16_t len); 193 194 /** 195 * \ingroup eSe_PAL 196 * \brief This function suspends execution of the calling thread for 197 * (at least) usec microseconds 198 * 199 * \param[in] usec - number of micro seconds to sleep 200 * 201 * \retval void 202 * 203 */ 204 void phPalEse_sleep(long usec); 205 206 /** 207 * \ingroup eSe_PAL 208 * \brief This function suspends execution of the calling thread for 209 * total_time usecs(max extra delay 1 usecs) with busy loop wait. 210 * Use this only for short delays (less than 500 microseconds) 211 * 212 * \param[in] usec - number of micro seconds to sleep 213 * 214 * \retval void 215 * 216 */ 217 void phPalEse_BusyWait(long total_time /* usecs*/); 218 219 /** 220 * \ingroup eSe_PAL 221 * \brief This function updates destination buffer with val 222 * data in len size 223 * 224 * \param[in] buff - Array to be updated 225 * \param[in] val - value to be updated 226 * \param[in] len - length of array to be updated 227 * 228 * \retval void 229 * 230 */ 231 void* phPalEse_memset(void* buff, int val, size_t len); 232 233 /** 234 * \ingroup eSe_PAL 235 * \brief This function copies source buffer to destination buffer 236 * data in len size 237 * 238 * \param[in] dest - Destination array to be updated 239 * \param[in] src - Source array to be updated 240 * \param[in] len - length of array to be updated 241 * 242 * \retval void 243 * 244 */ 245 void* phPalEse_memcpy(void* dest, const void* src, size_t len); 246 247 /** 248 * \ingroup eSe_PAL 249 * \brief This is utility function for runtime heap memory allocation 250 * 251 * \param[in] size - number of bytes to be allocated 252 * 253 * \retval void 254 * 255 */ 256 void* phPalEse_memalloc(uint32_t size); 257 258 /** 259 * \ingroup eSe_PAL 260 * \brief This is utility function for runtime heap memory allocation 261 * 262 * \param[in] dataType - type of data 263 * \param[in] size - number of bytes to be allocated 264 * \retval void 265 * 266 */ 267 void* phPalEse_calloc(size_t dataType, size_t size); 268 269 /** 270 * \ingroup eSe_PAL 271 * \brief This is utility function for freeing heap memory allocated 272 * 273 * \param[in] ptr - Address pointer to previous allocation 274 * 275 * \retval void 276 * 277 */ 278 void phPalEse_free(void* ptr); 279 280 /** 281 * \ingroup eSe_PAL 282 * \brief This is wrapper function for constructing timer objects. 283 * Timer is used for cmd TX and response RX time measurement. 284 * Applicable only for KPI measurement 285 * 286 * \param[in] void 287 * 288 * \retval void 289 * 290 */ 291 void phPalEse_initTimer(); 292 293 /** 294 * \ingroup eSe_PAL 295 * \brief Function for getting handle to initialized timers. 296 * Applicable only for KPI measurement 297 * 298 * \param[in] void 299 * 300 * \retval pointer to global phPalEse_NxpTimer_t struct or null 301 * 302 */ 303 const phPalEse_NxpTimer_t* phPalEse_getTimer(); 304 305 /** 306 * \ingroup eSe_PAL 307 * \brief Wrapper function to start timer. 308 * Applicable only for KPI measurement 309 * 310 * \param[in] pointer to NxpTimer object 311 * 312 * \retval void 313 * 314 */ 315 void phPalEse_startTimer(NxpTimer* timer); 316 317 /** 318 * \ingroup eSe_PAL 319 * \brief Wrapper function to stop timer. 320 * Applicable only for KPI measurement 321 * 322 * \param[in] pointer to NxpTimer object 323 * 324 * \retval void 325 * 326 */ 327 void phPalEse_stopTimer(NxpTimer* timer); 328 329 /** 330 * \ingroup eSe_PAL 331 * \brief Wrapper function to get total time recorded by given timer. 332 * Applicable only for KPI measurement 333 * 334 * \param[in] pointer to NxpTimer object 335 * 336 * \retval total time recorded by this timer 337 * 338 */ 339 unsigned long phPalEse_timerDuration(NxpTimer* timer); 340 341 /** 342 * \ingroup eSe_PAL 343 * \brief Wrapper function to reset the both timer state. 344 * Applicable only for KPI measurement 345 * 346 * \param[in] void 347 * 348 * \retval void 349 * 350 */ 351 void phPalEse_resetTimer(); 352 353 /** 354 * \ingroup eSe_PAL 355 * \brief Wrapper function to delete the objects created by initTimer. 356 * Applicable only for KPI measurement 357 * 358 * \param[in] void 359 * 360 * \retval void 361 * 362 */ 363 void phPalEse_deInitTimer(); 364 365 /** @} */ 366 #endif /* _PHNXPESE_PAL_H */ 367