drivers/ocotp/fsl_ocotp.h

0001 /*
0002  * Copyright 2019-2020 NXP
0003  * All rights reserved.
0004  *
0005  * SPDX-License-Identifier: BSD-3-Clause
0006  */
0007 #ifndef _FSL_OCOTP_H_
0008 #define _FSL_OCOTP_H_
0009
0010 #include "fsl_common.h"
0011
0012 /*!
0013  * @addtogroup ocotp
0014  * @{
0015  */
0016
0017 /*******************************************************************************
0018  * Definitions
0019  *******************************************************************************/
0020 /*! @name Driver version */
0021 /*@{*/
0022 /*! @brief OCOTP driver version. */
0023 #define FSL_OCOTP_DRIVER_VERSION (MAKE_VERSION(2, 1, 3))
0024 /*@}*/
0025
0026 #ifndef OCOTP_READ_FUSE_DATA_COUNT
0027 #define OCOTP_READ_FUSE_DATA_COUNT (1U)
0028 #endif
0029
0030 /*! @brief _ocotp_status Error codes for the OCOTP driver. */
0031 enum
0032 {
0033     kStatus_OCOTP_AccessError = MAKE_STATUS(kStatusGroup_SDK_OCOTP, 0), /*!< eFuse and shadow register access error. */
0034     kStatus_OCOTP_CrcFail     = MAKE_STATUS(kStatusGroup_SDK_OCOTP, 1), /*!< CRC check failed. */
0035     kStatus_OCOTP_ReloadError =
0036         MAKE_STATUS(kStatusGroup_SDK_OCOTP, 2), /*!< Error happens during reload shadow register. */
0037     kStatus_OCOTP_ProgramFail = MAKE_STATUS(kStatusGroup_SDK_OCOTP, 3), /*!< Fuse programming failed. */
0038     kStatus_OCOTP_Locked      = MAKE_STATUS(kStatusGroup_SDK_OCOTP, 4), /*!< Fuse is locked and cannot be programmed. */
0039 };
0040
0041 #if (defined(FSL_FEATURE_OCOTP_HAS_TIMING_CTRL) && FSL_FEATURE_OCOTP_HAS_TIMING_CTRL)
0042 /*! @brief OCOTP timing structure.
0043  *  Note that, these value are used for calcalating the read/write timings.
0044  *  And the values should statisfy below rules:
0045  *
0046  *  Tsp_rd=(WAIT+1)/ipg_clk_freq should be >= 150ns;
0047  *  Tsp_pgm=(RELAX+1)/ipg_clk_freq should be >= 100ns;
0048  *  Trd = ((STROBE_READ+1)- 2*(RELAX_READ+1)) /ipg_clk_freq,
0049  *  The Trd is required to be larger than 40 ns.
0050  *  Tpgm = ((STROBE_PROG+1)- 2*(RELAX_PROG+1)) /ipg_clk_freq;
0051  *  The Tpgm should be configured within the range of 9000 ns < Tpgm < 11000 ns;
0052  */
0053 typedef struct _ocotp_timing
0054 {
0055     uint32_t wait;        /*!< Wait time value to fill in the TIMING register. */
0056     uint32_t relax;       /*!< Relax time value to fill in the TIMING register. */
0057     uint32_t strobe_prog; /*!< Storbe program time value to fill in the TIMING register. */
0058     uint32_t strobe_read; /*!< Storbe read time value to fill in the TIMING register. */
0059 } ocotp_timing_t;
0060 #endif /* FSL_FEATURE_OCOTP_HAS_TIMING_CTRL */
0061
0062 /*******************************************************************************
0063  * API
0064  *******************************************************************************/
0065
0066 #if defined(__cplusplus)
0067 extern "C" {
0068 #endif
0069
0070 /*!
0071  * @brief Initializes OCOTP controller.
0072  *
0073  * @param base         OCOTP peripheral base address.
0074  * @param srcClock_Hz  source clock frequency in unit of Hz. When the macro
0075  * FSL_FEATURE_OCOTP_HAS_TIMING_CTRL is defined as 0, this parameter is not used,
0076  * application could pass in 0 in this case.
0077  */
0078 void OCOTP_Init(OCOTP_Type *base, uint32_t srcClock_Hz);
0079
0080 /*!
0081  * @brief De-initializes OCOTP controller.
0082  *
0083  * @retval kStatus_Success upon successful execution, error status otherwise.
0084  */
0085 void OCOTP_Deinit(OCOTP_Type *base);
0086
0087 /*!
0088  * @brief Checking the BUSY bit in CTRL register.
0089  * Checking this BUSY bit will help confirm if the OCOTP controller is ready for access.
0090  *
0091  * @param base         OCOTP peripheral base address.
0092  * @retval       true for bit set and false for cleared.
0093  */
0094 static inline bool OCOTP_CheckBusyStatus(OCOTP_Type *base)
0095 {
0096     return ((OCOTP_CTRL_BUSY_MASK == (base->CTRL & OCOTP_CTRL_BUSY_MASK)) ? (true) : (false));
0097 }
0098
0099 /*!
0100  * @brief Checking the ERROR bit in CTRL register.
0101  *
0102  * @param base         OCOTP peripheral base address.
0103  * @retval       true for bit set and false for cleared.
0104  */
0105 static inline bool OCOTP_CheckErrorStatus(OCOTP_Type *base)
0106 {
0107     return ((OCOTP_CTRL_ERROR_MASK == (base->CTRL & OCOTP_CTRL_ERROR_MASK)) ? (true) : (false));
0108 }
0109
0110 /*!
0111  * @brief Clear the error bit if this bit is set.
0112  *
0113  * @param base  OCOTP peripheral base address.
0114  */
0115 static inline void OCOTP_ClearErrorStatus(OCOTP_Type *base)
0116 {
0117     base->CTRL_CLR = OCOTP_CTRL_CLR_ERROR_MASK;
0118 }
0119
0120 /*!
0121  * @brief Reload the shadow register.
0122  * This function will help reload the shadow register without reseting the OCOTP module.
0123  * Please make sure the OCOTP has been initialized before calling this API.
0124  *
0125  * @param base OCOTP peripheral base addess.
0126  * @retval kStatus_Success Reload success.
0127  * @retval kStatus_OCOTP_ReloadError Reload failed.
0128  */
0129 status_t OCOTP_ReloadShadowRegister(OCOTP_Type *base);
0130
0131 /*!
0132  * @brief Read the fuse shadow register with the fuse addess.
0133  *
0134  * @deprecated Use @ref OCOTP_ReadFuseShadowRegisterExt instead of this function.
0135  *
0136  * @param base     OCOTP peripheral base address.
0137  * @param address  the fuse address to be read from.
0138  * @return The read out data.
0139  */
0140 uint32_t OCOTP_ReadFuseShadowRegister(OCOTP_Type *base, uint32_t address);
0141
0142 /*!
0143  * @brief Read the fuse shadow register from the fuse addess.
0144  *
0145  * This function reads fuse from @p address, how many words to read is specified
0146  * by the parameter @p fuseWords. This function could read at most
0147  * OCOTP_READ_FUSE_DATA_COUNT fuse word one time.
0148  *
0149  * @param base     OCOTP peripheral base address.
0150  * @param address  the fuse address to be read from.
0151  * @param data     Data array to save the readout fuse value.
0152  * @param fuseWords How many words to read.
0153  * @retval kStatus_Success Read success.
0154  * @retval kStatus_Fail Error occurs during read.
0155  */
0156 status_t OCOTP_ReadFuseShadowRegisterExt(OCOTP_Type *base, uint32_t address, uint32_t *data, uint8_t fuseWords);
0157
0158 /*!
0159  * @brief Write the fuse shadow register with the fuse addess and data.
0160  * Please make sure the wrtie address is not locked while calling this API.
0161  *
0162  * @param base     OCOTP peripheral base address.
0163  * @param address  the fuse address to be written.
0164  * @param data     the value will be writen to fuse address.
0165  * @retval   write status, kStatus_Success for success and kStatus_Fail for failed.
0166  */
0167 status_t OCOTP_WriteFuseShadowRegister(OCOTP_Type *base, uint32_t address, uint32_t data);
0168
0169 /*!
0170  * @brief Write the fuse shadow register and lock it.
0171  *
0172  * Please make sure the wrtie address is not locked while calling this API.
0173  *
0174  * Some OCOTP controller supports ECC mode and redundancy mode (see reference mananual
0175  * for more details). OCOTP controller will auto select ECC or redundancy
0176  * mode to program the fuse word according to fuse map definition. In ECC mode, the
0177  * 32 fuse bits in one word can only be written once. In redundancy mode, the word can
0178  * be written more than once as long as they are different fuse bits. Set parameter
0179  * @p lock as true to force use ECC mode.
0180  *
0181  * @param base     OCOTP peripheral base address.
0182  * @param address  The fuse address to be written.
0183  * @param data     The value will be writen to fuse address.
0184  * @param lock     Lock or unlock write fuse shadow register operation.
0185  * @retval kStatus_Success Program and reload success.
0186  * @retval kStatus_OCOTP_Locked The eFuse word is locked and cannot be programmed.
0187  * @retval kStatus_OCOTP_ProgramFail eFuse word programming failed.
0188  * @retval kStatus_OCOTP_ReloadError eFuse word programming success, but
0189  *         error happens during reload the values.
0190  * @retval kStatus_OCOTP_AccessError Cannot access eFuse word.
0191  */
0192 status_t OCOTP_WriteFuseShadowRegisterWithLock(OCOTP_Type *base, uint32_t address, uint32_t data, bool lock);
0193
0194 /*!
0195  * @brief Get the OCOTP controller version from the register.
0196  *
0197  * @param base    OCOTP peripheral base address.
0198  * @retval  return the version value.
0199  */
0200 static inline uint32_t OCOTP_GetVersion(OCOTP_Type *base)
0201 {
0202     return (base->VERSION);
0203 }
0204
0205 #if defined(__cplusplus)
0206 }
0207 #endif
0208
0209 /*! @}*/
0210
0211 #endif /* _FSL_OCOTP_H_ */