1 /* 2 * Copyright 2023 NXP 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 #ifndef _FSL_GLIKEY_H_ 8 #define _FSL_GLIKEY_H_ 9 10 #include "fsl_common.h" 11 12 /*! 13 * @addtogroup GLIKEY 14 * @{ 15 */ 16 17 /*! @file */ 18 19 /******************************************************************************* 20 * Definitions 21 *******************************************************************************/ 22 23 /*! @name Driver version */ 24 /*@{*/ 25 /*! @brief Defines GLIKEY driver version 2.0.0. 26 * 27 * Change log: 28 * - Version 2.0.0 29 * - Initial version 30 */ 31 #define FSL_GLIKEY_DRIVER_VERSION (MAKE_VERSION(2, 0, 0)) 32 33 enum 34 { 35 kStatus_GLIKEY_LockedError = 36 MAKE_STATUS(kStatusGroup_GLIKEY, 0x1u), /*!< GLIKEY status for locked SFR registers (unexpected) . */ 37 kStatus_GLIKEY_NotLocked = MAKE_STATUS(kStatusGroup_GLIKEY, 0x2u), /*!< GLIKEY status for unlocked SFR registers. */ 38 kStatus_GLIKEY_Locked = MAKE_STATUS(kStatusGroup_GLIKEY, 0x3u), /*!< GLIKEY status for locked SFR registers. */ 39 kStatus_GLIKEY_DisabledError = MAKE_STATUS(kStatusGroup_GLIKEY, 0x4u), /*!< GLIKEY status for disabled error. */ 40 }; 41 42 /* [Design] 43 Value: XX YZ UU VW 44 - XX: F0: write to WR_EN1, 0F: do not write to WR_EN1 45 - UU: F0: write to WR_EN0, 0F: do not write to WR_EN0 46 - Y: equal to <step> ^ W 47 - Z: value to write to WR_EN1 or equal to ~W 48 - V: equal to <step> ^ Z 49 - W: value to write to WR_EN0 or equal to ~Z 50 Invariant: XXYZ ^ UUVW == 0xFFFF 51 */ 52 #define GLIKEY_CODEWORD_STEP1 ((uint32_t)0xF0C10F3EU) /*< Codeword for transition from STEP1 --> STEP2 */ 53 #define GLIKEY_CODEWORD_STEP2 ((uint32_t)0x0F1DF0E2U) /*< Codeword for transition from STEP2 --> STEP3 */ 54 #define GLIKEY_CODEWORD_STEP3 ((uint32_t)0xF0B00F4FU) /*< Codeword for transition from STEP3 --> STEP4 */ 55 #define GLIKEY_CODEWORD_STEP4 ((uint32_t)0x0F4EF0B1U) /*< Codeword for transition from STEP4 --> STEP5 */ 56 #define GLIKEY_CODEWORD_STEP5 ((uint32_t)0xF0810F7EU) /*< Codeword for transition from STEP5 --> STEP6 */ 57 #define GLIKEY_CODEWORD_STEP6 ((uint32_t)0x0F5DF0A2U) /*< Codeword for transition from STEP6 --> STEP7 */ 58 #define GLIKEY_CODEWORD_STEP7 ((uint32_t)0xF0700F8FU) /*< Codeword for transition from STEP7 --> STEP8 */ 59 #define GLIKEY_CODEWORD_STEP_EN ((uint32_t)0x0FFFF000U) /*< Codeword for transition from STEP 4/8 --> WR_EN */ 60 61 #define GLIKEY_FSM_WR_DIS 0x0Bu 62 #define GLIKEY_FSM_INIT 0x16u 63 #define GLIKEY_FSM_STEP1 0x2Cu 64 #define GLIKEY_FSM_STEP2 0x58u 65 #define GLIKEY_FSM_STEP3 0xB0u 66 #define GLIKEY_FSM_STEP4 0x160u 67 #define GLIKEY_FSM_LOCKED 0xC01u 68 #define GLIKEY_FSM_WR_EN 0x1802u 69 #define GLIKEY_FSM_SSR_RESET 0x1005u 70 71 /*@}*/ 72 73 /******************************************************************************* 74 * API 75 *******************************************************************************/ 76 77 #if defined(__cplusplus) 78 extern "C" { 79 #endif /* __cplusplus */ 80 81 /*! 82 * @name GLIKEY Functional Operation 83 * @{ 84 */ 85 86 /*! 87 * @brief Retreives the current status of Glikey. 88 * 89 * @param[in] base The base address of the Glikey instance 90 * 91 * @return Glikey status information 92 */ 93 uint32_t GLIKEY_GetStatus(GLIKEY_Type *base); 94 95 /*! 96 * @brief Get if Glikey is locked 97 * 98 * This operation returns the locking status of Glikey. 99 * 100 * @return Status 101 * @retval kStatus_GLIKEY_Locked if locked 102 * @retval kStatus_GLIKEY_NotLocked if unlocked 103 */ 104 status_t GLIKEY_IsLocked(GLIKEY_Type *base); 105 106 /*! 107 * @brief Check if Glikey is locked 108 * 109 * This operation returns the locking status of Glikey. 110 * 111 * @return Status kStatus_Success if success 112 * @retval kStatus_GLIKEY_LockedError if locked 113 * @retval kStatus_GLIKEY_NotLocked if unlocked 114 */ 115 status_t GLIKEY_CheckLock(GLIKEY_Type *base); 116 117 #if defined(GLIKEY_VERSION_FSM_CONFIG) 118 /*! 119 * @brief Retreives the version and configuration of Glikey. 120 * 121 * 122 * @param[in] base The base address of the Glikey instance 123 * @param[out] result Pointer which will be filled with the Glikey hardware version 124 * 125 * @return Status kStatus_Success if success 126 */ 127 status_t GLIKEY_GetVersion(GLIKEY_Type *base, uint32_t *result); 128 #endif /* GLIKEY_VERSION_FSM_CONFIG */ 129 130 /*! 131 * @brief Perform a synchronous reset of Glikey. 132 * 133 * This function performs a synchrounous reset of the Glikey. This results in: 134 * - Glikey will return to the INIT state, unless it is in the LOCK state 135 * 136 * @param[in] base The base address of the Glikey instance 137 * 138 * @return Status kStatus_Success if success 139 * Possible errors: kStatus_GLIKEY_LockedError 140 */ 141 status_t GLIKEY_SyncReset(GLIKEY_Type *base); 142 143 /*! 144 * @brief Set interrupt enable flag of Glikey. 145 * 146 * @param[in] base The base address of the Glikey instance 147 * @param[in] value Value to set the interrupt enable flag to, see #[TODO: add reference to constants] 148 * 149 * @return Status kStatus_Success if success 150 * Possible errors: kStatus_GLIKEY_LockedError 151 */ 152 status_t GLIKEY_SetIntEnable(GLIKEY_Type *base, uint32_t value); 153 154 /*! 155 * @brief Get interrupt enable flag of Glikey. 156 * 157 * @param[in] base The base address of the Glikey instance 158 * @param[out] value Pointer which will be filled with the interrupt enable status, see #[TODO: add reference to 159 * constants] 160 * 161 * @return Status kStatus_Success if success 162 */ 163 status_t GLIKEY_GetIntEnable(GLIKEY_Type *base, uint32_t *value); 164 165 /*! 166 * @brief Clear the interrupt status flag of Glikey. 167 * 168 * @param[in] base The base address of the Glikey instance 169 * 170 * @return Status kStatus_Success if success 171 * Possible errors: kStatus_GLIKEY_LockedError 172 */ 173 status_t GLIKEY_ClearIntStatus(GLIKEY_Type *base); 174 175 /*! 176 * @brief Set the interrupt status flag of Glikey. 177 * 178 * @param[in] base The base address of the Glikey instance 179 * 180 * @return Status kStatus_Success if success 181 * Possible errors: kStatus_GLIKEY_LockedError 182 */ 183 status_t GLIKEY_SetIntStatus(GLIKEY_Type *base); 184 185 /*! 186 * @brief Lock Glikey SFR (Special Function Registers) interface 187 * 188 * This operation locks the Glikey SFR interface if it is not locked yet. 189 * 190 * @param[in] base The base address of the Glikey instance 191 * 192 * @return Status kStatus_Success if success 193 */ 194 status_t GLIKEY_Lock(GLIKEY_Type *base); 195 196 /*! 197 * @brief Lock Glikey index 198 * 199 * This operation is used to lock a Glikey index. It can only be executed from the WR_EN state, 200 * executing it from any other state will result in Glikey entering WR_DIS state. When this happens 201 * Glikey requires a reset (synchrous or asynchronous) to go back to INIT state. 202 * If the Glikey SFR lock is active this operation will return an error. 203 * 204 * @param[in] base The base address of the Glikey instance 205 * 206 * @return Status kStatus_Success if success 207 * Possible errors: kStatus_GLIKEY_LockedError, kStatus_GLIKEY_DisabledError 208 */ 209 status_t GLIKEY_LockIndex(GLIKEY_Type *base); 210 211 /*! 212 * @brief Check if Glikey index is locked 213 * 214 * This operation returns the locking status of Glikey index. 215 * 216 * @param[in] base The base address of the Glikey instance 217 * @param[in] index The index of the Glikey instance 218 * 219 * @return kStatus_GLIKEY_Locked if locked, kStatus_GLIKEY_NotLocked if unlocked 220 * Possible errors: kStatus_Fail 221 */ 222 status_t GLIKEY_IsIndexLocked(GLIKEY_Type *base, uint32_t index); 223 224 /** 225 * @brief Start Glikey enable 226 * 227 * This operation is used to set a new index and start a the sequence to enable it. It needs to be 228 * started from the INIT state. If the new index is already locked Glikey will go to LOCKED state, 229 * otherwise it will go to STEP1 state. 230 * If this operation is used when Glikey is in any state other than INIT Glikey will go to WR_DIS 231 * state. It can only recover from this state through a reset (synchrounous or asyncrhonous). 232 * If the Glikey SFR lock is active this operation will return an error. 233 * 234 * @param[in] base The base address of the Glikey instance 235 * @param[in] index The index of the Glikey instance 236 * 237 * @return Status kStatus_Success if success 238 * Possible errors: kStatus_GLIKEY_LockedError, kStatus_Fail 239 */ 240 status_t GLIKEY_StartEnable(GLIKEY_Type *base, uint32_t index); 241 242 /** 243 * @brief Continue Glikey enable 244 * 245 * This operation is used to progress through the different states of the state machine, starting 246 * from STEP1 until the state WR_EN is reached. Each next state of the state machine can only be 247 * reached by providing the right codeword to this function. If anything goes wrong the state machine 248 * will go to WR_DIS state and can only recover from it through a reset (synchrous or asynchronous). 249 * If the Glikey SFR lock is active this operation will return an error. 250 * 251 * @param[in] base The base address of the Glikey instance 252 * @param[in] codeword Encoded word for progressing to next FSM state (see GLIKEY_CODEWORD_STEPx/EN) 253 * 254 * @return Status kStatus_Success if success 255 * Possible errors: kStatus_GLIKEY_LockedError, kStatus_Fail, kStatus_GLIKEY_DisabledError 256 */ 257 /* [Design] 258 - Check if Glikey is locked 259 if ( GLIKEY_LOCKED == GLIKEY_GET_SFR_LOCK(base) ) return NXPCLGLIKEY_STATUS_LOCKED_ERROR 260 - Decode the codeword and write to Glikey CTRL[] 261 Write GLIKEY_CTRL(base, EnableSelect, EnableValue) 262 - Check if an error occured 263 - the only possible error here is FSM error which results in a transition to WR_DIS state 264 - alternatively this can be confirmed by checking FSM state value 265 - Only now we will check if the codeword itself is valid 266 - this is done in this order to assure that the state machine reaches WR_DIS state when needed 267 - check if XXYZ^UUVW == 0xFFFF and return kStatus_Fail when it fails 268 - Return kStatus_Success 269 */ 270 status_t GLIKEY_ContinueEnable(GLIKEY_Type *base, uint32_t codeword); 271 272 /** 273 * @brief End Glikey operation 274 * 275 * This operation is used to end a Glikey operation. It can only be executed from the WR_EN, LOCKED 276 * and RESET states. Executing it from any other state will result in Glikey entering WR_DIS state. 277 * When this happens Glikey requires a reset (synchrous or asynchronous) to go back to INIT state. 278 * After this operation Glikey will go to INIT state or stay in LOCKED state when the index was locked. 279 * If the Glikey SFR lock is active this operation will return an error. 280 * 281 * @return A code-flow protected error code (see @ref nxpCsslFlowProtection) 282 * 283 * @param[in] base The base address of the Glikey instance 284 * 285 * @return Status kStatus_Success if success, kStatus_GLIKEY_Locked if index is still locked 286 * Possible errors: kStatus_GLIKEY_LockedError, kStatus_GLIKEY_DisabledError 287 */ 288 status_t GLIKEY_EndOperation(GLIKEY_Type *base); 289 290 /** 291 * @brief Reset Glikey index 292 * 293 * This operation is used to reset a Glikey index. It can only be executed from the INIT state, 294 * executing it from any other state will result in Glikey entering WR_DIS state. When this happens 295 * Glikey requires a reset (synchrous or asynchronous) to go back to INIT state. 296 * If the Glikey SFR lock is active or the index is locked this operation will return an error. 297 * 298 * @return A code-flow protected error code (see @ref nxpCsslFlowProtection) 299 * 300 * @return Status kStatus_Success if success, kStatus_GLIKEY_Locked if index is still locked 301 * Possible errors: kStatus_GLIKEY_LockedError, kStatus_GLIKEY_DisabledError 302 */ 303 status_t GLIKEY_ResetIndex(GLIKEY_Type *base, uint32_t index); 304 305 /*! @}*/ 306 307 #if defined(__cplusplus) 308 } 309 #endif /* __cplusplus */ 310 311 /*! @}*/ /* end of group glikey */ 312 313 #endif /* _FSL_GLIKEY_H_ */ 314
