1 /* 2 * Copyright 2024 NXP 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef _FSL_ELE_BASE_API_H_ 9 #define _FSL_ELE_BASE_API_H_ 10 11 #include "fsl_common.h" 12 #include "fsl_device_registers.h" 13 14 /*! @addtogroup ele_base_api */ 15 /*! @{ */ 16 17 /*! @file */ 18 19 /******************************************************************************* 20 * Configurations 21 ******************************************************************************/ 22 23 24 /******************************************************************************* 25 * Definitions 26 ******************************************************************************/ 27 #define RESPONSE_SUCCESS (0xd6u) 28 #define SHIFT_16 (16u) 29 #define SHIFT_8 (8u) 30 #define MSG_RESPONSE_MAX (16u) 31 #define MSG_TAG_CMD (0x17u) 32 #define MSG_TAG_RESP (0xE1u) 33 34 #define PING (0x17010106u) 35 #define PING_SIZE (0x1u) 36 #define PING_RESPONSE_HDR (0xe1010206u) 37 38 #define GET_FW_VERSION (0x179D0106u) 39 #define GET_FW_VERSION_SIZE (0x1u) 40 #define GET_FW_VERSION_RESPONSE_HDR (0xe19D0406u) 41 42 #define CLOCK_CHANGE_START (0x17100106u) 43 #define CLOCK_CHANGE_START_SIZE (0x1u) 44 #define CLOCK_CHANGE_START_RESPONSE_HDR (0xe1100206u) 45 46 #define CLOCK_CHANGE_FINISH (0x17110206u) 47 #define CLOCK_CHANGE_FINISH_SIZE (0x2u) 48 #define CLOCK_CHANGE_FINISH_RESPONSE_HDR (0xe1110206u) 49 50 #define VOLTAGE_CHANGE_START (0x17120106u) 51 #define VOLTAGE_CHANGE_START_SIZE (0x1u) 52 #define VOLTAGE_CHANGE_START_RESPONSE_HDR (0xe1120206u) 53 54 #define VOLTAGE_CHANGE_FINISH (0x17130106u) 55 #define VOLTAGE_CHANGE_FINISH_SIZE (0x1u) 56 #define VOLTAGE_CHANGE_FINISH_RESPONSE_HDR (0xe1130206u) 57 58 #define GET_FW_STATUS (0x17C50106u) 59 #define GET_FW_STATUS_SIZE (0x1u) 60 #define GET_FW_STATUS_RESPONSE_HDR (0xe1C50306u) 61 62 #define ENABLE_APC (0x17D20106u) 63 #define ENABLE_APC_SIZE (0x1u) 64 #define ENABLE_APC_RESPONSE_HDR (0xe1D20206u) 65 66 #define START_RNG (0x17a30106u) 67 #define START_RNG_SIZE (0x1u) 68 #define START_RNG_RESPONSE_HDR (0xe1a30206u) 69 70 #define FORWARD_LIFECYCLE (0x17950206u) 71 #define FORWARD_LIFECYCLE_SIZE (0x2u) 72 #define FORWARD_LIFECYCLE_RESPONSE_HDR (0xe1950206u) 73 74 #if defined(FSL_FEATURE_SOC_OTFAD_COUNT) && (FSL_FEATURE_SOC_OTFAD_COUNT > 1) 75 #define ENABLE_OTFAD (0x17c60206u) 76 #define ENABLE_OTFAD_SIZE (2u) 77 #else 78 #define ENABLE_OTFAD (0x17c60106u) 79 #define ENABLE_OTFAD_SIZE (1u) 80 #endif /* FSL_FEATURE_SOC_OTFAD_COUNT */ 81 #define ENABLE_OTFAD_RESPONSE_HDR (0xe1c60206u) 82 83 #define RELEASE_RDC (0x17C40206u) 84 #define RELEASE_RDC_SIZE (0x2u) 85 #define RELEASE_RDC_RESPONSE_HDR (0xe1C40206u) 86 87 /*! @name Driver version */ 88 /*@{*/ 89 /*! @brief Defines ELE Base API version 1.0.1.*/ 90 #define FSL_ELE_BASE_API_DRIVER_VERSION (MAKE_VERSION(1, 0, 1)) 91 /*@}*/ 92 93 94 /******************************************************************************* 95 * API 96 ******************************************************************************/ 97 98 #if defined(__cplusplus) 99 extern "C" { 100 #endif /* __cplusplus */ 101 102 /*! 103 * @brief Ping ELE 104 * 105 * This function Ping EdgeLock Enclave, can be sent at any time to verify ELE is alive. 106 * Additionally, this command reloads the fuse shadow registers and kick the Sentinel active bit. 107 * This active bit must be kicked at least once every day (24 hours). 108 * 109 * @param mu MU peripheral base address 110 * 111 * @return Status kStatus_Success if success, kStatus_Fail if fail 112 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 113 */ 114 status_t ELE_BaseAPI_Ping(S3MU_Type *mu); 115 116 /*! 117 * @brief Get ELE FW Version 118 * 119 * This function is used to retrieve the Sentinel FW version. 120 * 121 * @param mu MU peripheral base address 122 * @param EleFwVersion Pointer where ElE firmware version will be stored 123 * 124 * @return Status kStatus_Success if success, kStatus_Fail if fail 125 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 126 */ 127 status_t ELE_BaseAPI_GetFwVersion(S3MU_Type *mu, uint32_t *EleFwVersion); 128 129 /*! 130 * @brief Get ELE FW Status 131 * 132 * This function is used to retrieve the Sentinel FW status. 133 * 134 * @param mu MU peripheral base address 135 * @param EleFwStatus Pointer where ElE firmware status will be stored 136 * 137 * @return Status kStatus_Success if success, kStatus_Fail if fail 138 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 139 */ 140 status_t ELE_BaseAPI_GetFwStatus(S3MU_Type *mu, uint32_t *EleFwStatus); 141 142 /*! 143 * @brief Enable APC (Application core) 144 * 145 * This function is used by RTC (real time core) to release APC (Application core) when needed. 146 * 147 * @param mu MU peripheral base address 148 * 149 * @return Status kStatus_Success if success, kStatus_Fail if fail 150 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 151 */ 152 status_t ELE_BaseAPI_EnableAPC(S3MU_Type *mu); 153 154 /*! 155 * @brief Forward Lifecycle update 156 * 157 * This function is to change chip lifecycle 158 * 0x01U for NXP provisoned 159 * 0x02U for OEM Open 160 * 0x08U for OEM Closed 161 * 0x80U for OEM Locked 162 * 163 * @param mu MU peripheral base address 164 * @param Lifecycle to switch 165 * 166 * @return Status kStatus_Success if success, kStatus_Fail if fail 167 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 168 */ 169 status_t ELE_BaseAPI_ForwardLifecycle(S3MU_Type *mu, uint32_t Lifecycle); 170 171 /*! 172 * @brief Release RDC 173 * 174 * This function is used to release specifed RDC to the core identified in this function. 175 * The RDC will be released only if the FW of the core to which is the RDC ownership is going to be 176 * transferred has been properly authenticated and verified. 177 * 178 * @param mu MU peripheral base address 179 * @param RdcID Resource Domain Control identifier 180 * @param CoreID Core identifier 181 * 182 * @return Status kStatus_Success if success, kStatus_Fail if fail 183 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 184 */ 185 status_t ELE_BaseAPI_ReleaseRDC(S3MU_Type *mu, uint32_t RdcID, uint32_t CoreID); 186 187 /*! 188 * @brief Start the initialization of the RNG context. 189 * 190 * The RNG must be started before using some of the ELE services. 191 * 192 * @param mu MU peripheral base address 193 * 194 * @return Status kStatus_Success if success, kStatus_Fail if fail 195 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 196 */ 197 status_t ELE_BaseAPI_StartRng(S3MU_Type *mu); 198 199 /*! 200 * @brief Enable an instance of OTFAD. 201 * 202 * @param mu MU peripheral base address 203 * @param OtfadID ID of the OTFAD instance to enable - used only if there are 204 * multiple instances on the SoC 205 * 206 * @return Status kStatus_Success if success, kStatus_Fail if fail 207 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 208 */ 209 status_t ELE_BaseAPI_EnableOtfad(S3MU_Type *mu, uint8_t OtfadID); 210 211 /*! 212 * @brief Start the clock change process 213 * 214 * @param mu MU peripheral base address 215 * 216 * @return Status kStatus_Success if success, kStatus_Fail if fail 217 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 218 */ 219 status_t ELE_BaseAPI_ClockChangeStart(S3MU_Type *mu); 220 221 /*! 222 * @brief Change ELE and/or CM33 clock 223 * 224 * It is valid to pass both parameters at the same time if the SoC supports both. 225 * 226 * @param mu MU peripheral base address 227 * @param NewClockRateELE the new clock rate for ELE 228 * @param NewClockRateCM33 the new clock rate for the CM33 core 229 * 230 * @return Status kStatus_Success if success, kStatus_Fail if fail 231 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 232 */ 233 status_t ELE_BaseAPI_ClockChangeFinish(S3MU_Type *mu, uint8_t NewClockRateELE, uint8_t NewClockRateCM33); 234 235 /*! 236 * @brief Start the voltage change process 237 * 238 * @param mu MU peripheral base address 239 * 240 * @return Status kStatus_Success if success, kStatus_Fail if fail 241 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 242 */ 243 status_t ELE_BaseAPI_VoltageChangeStart(S3MU_Type *mu); 244 245 /*! 246 * @brief Finish the voltage change process 247 * 248 * @param mu MU peripheral base address 249 * 250 * @return Status kStatus_Success if success, kStatus_Fail if fail 251 * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange 252 */ 253 status_t ELE_BaseAPI_VoltageChangeFinish(S3MU_Type *mu); 254 255 #if defined(__cplusplus) 256 } 257 #endif /* __cplusplus */ 258 259 /*! @} */ 260 261 262 #endif /* _FSL_ELE_BASE_API_H_ */ 263
