drivers/bee/fsl_bee.h

0001 /*
0002  * Copyright 2017, 2019 NXP
0003  * All rights reserved.
0004  *
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008
0009 #ifndef _FSL_BEE_H_
0010 #define _FSL_BEE_H_
0011
0012 #include "fsl_common.h"
0013
0014 /*!
0015  * @addtogroup bee
0016  * @{
0017  */
0018
0019 /*******************************************************************************
0020  * Definitions
0021  *******************************************************************************/
0022
0023 /*! @name Driver version */
0024 /*@{*/
0025 /*! @brief BEE driver version. Version 2.0.2.
0026  *
0027  * Current version: 2.0.2
0028  *
0029  * Change log:
0030  *
0031  * - 2.0.2
0032  *   - Bug Fixes
0033  *     - Fixed MISRA issue.
0034  *
0035  * - 2.0.1
0036  *   - Bug Fixes
0037  *    - Fixed bug in key user key loading sequence. BEE must be enabled during loading of user key.
0038  *    - Fixed typos in comments.
0039  *   - New Features
0040  *    - Added configuration setting for endian swap, access permission and region security level.
0041  *   - Improvements
0042  *    - Setting of AES nonce was moved from BEE_SetRegionKey() into separate BEE_SetRegionNonce() function.
0043  *     - Changed handling of region settings. Both regions are configured simultaneously by BEE_SetConfig() function.
0044  *      Configuration of FAC start and end address using IOMUXC_GPRs was moved to application.
0045  *    - Default value for region address offset was changed to 0.
0046  *
0047  * - 2.0.0
0048  *   - Initial version
0049  */
0050 #define FSL_BEE_DRIVER_VERSION (MAKE_VERSION(2, 0, 2))
0051 /*@}*/
0052
0053 /*! @brief BEE aes mode. */
0054 typedef enum _bee_aes_mode
0055 {
0056     kBEE_AesEcbMode = 0U, /*!< AES ECB Mode */
0057     kBEE_AesCtrMode = 1U  /*!< AES CTR Mode */
0058 } bee_aes_mode_t;
0059
0060 /*! @brief BEE region. */
0061 typedef enum _bee_region
0062 {
0063     kBEE_Region0 = 0U, /*!< BEE region 0 */
0064     kBEE_Region1 = 1U  /*!< BEE region 1 */
0065 } bee_region_t;
0066
0067 /*! @brief BEE ac prot enable. */
0068 typedef enum _bee_ac_prot_enable
0069 {
0070     kBEE_AccessProtDisabled = 0U, /*!< BEE access permission control disabled */
0071     kBEE_AccessProtEnabled  = 1U  /*!< BEE access permission control enabled */
0072 } bee_ac_prot_enable;
0073
0074 /*! @brief BEE endian swap enable. */
0075 typedef enum _bee_endian_swap_enable
0076 {
0077     kBEE_EndianSwapDisabled = 1U, /*!< BEE endian swap disabled */
0078     kBEE_EndianSwapEnabled  = 0U  /*!< BEE endian swap enabled */
0079 } bee_endian_swap_enable;
0080
0081 /*! @brief BEE security level. */
0082 typedef enum _bee_security_level
0083 {
0084     kBEE_SecurityLevel0 = 0U, /*!< BEE security level 0 */
0085     kBEE_SecurityLevel1 = 1U, /*!< BEE security level 1 */
0086     kBEE_SecurityLevel2 = 2U, /*!< BEE security level 2 */
0087     kBEE_SecurityLevel3 = 3U  /*!< BEE security level 3 */
0088 } bee_security_level;
0089
0090 /*! @brief BEE status flags. */
0091 typedef enum _bee_status_flags
0092 {
0093     kBEE_DisableAbortFlag     = 1U,                      /*!< Disable abort flag. */
0094     kBEE_Reg0ReadSecViolation = 2U,                      /*!< Region-0 read channel security violation */
0095     kBEE_ReadIllegalAccess    = 4U,                      /*!< Read channel illegal access detected */
0096     kBEE_Reg1ReadSecViolation = 8U,                      /*!< Region-1 read channel security violation */
0097     kBEE_Reg0AccessViolation  = 16U,                     /*!< Protected region-0 access violation */
0098     kBEE_Reg1AccessViolation  = 32U,                     /*!< Protected region-1 access violation */
0099     kBEE_IdleFlag             = BEE_STATUS_BEE_IDLE_MASK /*!< Idle flag */
0100 } bee_status_flags_t;
0101
0102 /*! @brief BEE region configuration structure. */
0103 typedef struct _bee_region_config
0104 {
0105     bee_aes_mode_t region0Mode;          /*!< AES mode used for encryption/decryption for region 0 */
0106     bee_aes_mode_t region1Mode;          /*!< AES mode used for encryption/decryption for region 1 */
0107     uint32_t region0AddrOffset;          /*!< Region 0 address offset */
0108     uint32_t region1AddrOffset;          /*!< Region 1 address offset */
0109     bee_security_level region0SecLevel;  /*!< Region 0 security level */
0110     bee_security_level region1SecLevel;  /*!< Region 1 security level */
0111     uint32_t region1Bot;                 /*!< Region 1 bottom address */
0112     uint32_t region1Top;                 /*!< Region 1 top address */
0113     bee_ac_prot_enable accessPermission; /*!< Access permission control enable/disable */
0114     bee_endian_swap_enable endianSwapEn; /*!< Endian swap enable/disable */
0115 } bee_region_config_t;
0116
0117 /*******************************************************************************
0118  * API
0119  ******************************************************************************/
0120 #if defined(__cplusplus)
0121 extern "C" {
0122 #endif
0123
0124 /*!
0125  * @brief Resets BEE module to factory default values.
0126  *
0127  * This function performs hardware reset of BEE module. Attributes and keys from software for both regions are cleared.
0128  *
0129  * @param base BEE peripheral address.
0130  */
0131 void BEE_Init(BEE_Type *base);
0132
0133 /*!
0134  * @brief Resets BEE module, clears keys for both regions and disables clock to the BEE.
0135  *
0136  * This function performs hardware reset of BEE module and disables clocks. Attributes and keys from software for both
0137  * regions are cleared.
0138  *
0139  * @param base BEE peripheral address.
0140  */
0141 void BEE_Deinit(BEE_Type *base);
0142
0143 /*!
0144  * @brief Enables BEE decryption.
0145  *
0146  * This function enables decryption using BEE.
0147  *
0148  * @param base BEE peripheral address.
0149  */
0150 static inline void BEE_Enable(BEE_Type *base)
0151 {
0152     base->CTRL |= BEE_CTRL_BEE_ENABLE_MASK;
0153 }
0154
0155 /*!
0156  * @brief Disables BEE decryption.
0157  *
0158  * This function disables decryption using BEE.
0159  *
0160  * @param base BEE peripheral address.
0161  */
0162 static inline void BEE_Disable(BEE_Type *base)
0163 {
0164     base->CTRL &= ~BEE_CTRL_BEE_ENABLE_MASK;
0165 }
0166
0167 /*!
0168  * @brief Loads default values to the BEE region configuration structure.
0169  *
0170  * Loads default values to the BEE region configuration structure. The default values are as follows:
0171  * @code
0172  *   config->region0Mode = kBEE_AesCtrMode;
0173  *   config->region1Mode = kBEE_AesCtrMode;
0174  *   config->region0AddrOffset = 0U;
0175  *   config->region1AddrOffset = 0U;
0176  *   config->region0SecLevel = kBEE_SecurityLevel3;
0177  *   config->region1SecLevel = kBEE_SecurityLevel3;
0178  *   config->region1Bot = 0U;
0179  *   config->region1Top = 0U;
0180  *   config->accessPermission = kBEE_AccessProtDisabled;
0181  *   config->endianSwapEn = kBEE_EndianSwapEnabled;
0182  * @endcode
0183  *
0184  * @param config Configuration structure for BEE peripheral.
0185  */
0186 void BEE_GetDefaultConfig(bee_region_config_t *config);
0187
0188 /*!
0189  * @brief Sets BEE configuration.
0190  *
0191  * This function sets BEE peripheral and BEE region settings accorging to given configuration structure.
0192  *
0193  * @param base BEE peripheral address.
0194  * @param config Configuration structure for BEE.
0195  */
0196 void BEE_SetConfig(BEE_Type *base, const bee_region_config_t *config);
0197
0198 /*!
0199  * @brief Loads the AES key for selected region into BEE key registers.
0200  *
0201  * This function loads given AES key to BEE register for the given region.
0202  * The key must be 32-bit aligned and stored in little-endian format.
0203  *
0204  * Please note, that eFuse BEE_KEYx_SEL must be set accordingly to be able to load and use key loaded in BEE registers.
0205  * Otherwise, key cannot loaded and BEE will use key from OTPMK or SW_GP2.
0206  *
0207  * @param base BEE peripheral address.
0208  * @param region Selection of the BEE region to be configured.
0209  * @param key AES key (in little-endian format).
0210  * @param keySize Size of AES key.
0211  */
0212 status_t BEE_SetRegionKey(BEE_Type *base, bee_region_t region, const uint8_t *key, size_t keySize);
0213
0214 /*!
0215  * @brief Loads the nonce for selected region into BEE nonce registers.
0216  *
0217  * This function loads given nonce(only AES CTR mode) to BEE register for the given region.
0218  * The nonce must be 32-bit aligned and stored in little-endian format.
0219  *
0220  * @param base BEE peripheral address.
0221  * @param region Selection of the BEE region to be configured.
0222  * @param nonce AES nonce (in little-endian format).
0223  * @param nonceSize Size of AES nonce.
0224  */
0225 status_t BEE_SetRegionNonce(BEE_Type *base, bee_region_t region, const uint8_t *nonce, size_t nonceSize);
0226
0227 /*!
0228  * @brief Gets the BEE status flags.
0229  *
0230  * This function returns status of BEE peripheral.
0231  *
0232  * @param base BEE peripheral address.
0233  *
0234  * @return The status flags. This is the logical OR of members of the
0235  *         enumeration ::bee_status_flags_t
0236  */
0237 uint32_t BEE_GetStatusFlags(BEE_Type *base);
0238
0239 /*!
0240  * @brief Clears the BEE status flags.
0241  *
0242  * @param base BEE peripheral base address.
0243  * @param mask The status flags to clear. This is a logical OR of members of the
0244  *             enumeration ::bee_status_flags_t
0245  */
0246 void BEE_ClearStatusFlags(BEE_Type *base, uint32_t mask);
0247
0248 #if defined(__cplusplus)
0249 }
0250 #endif
0251
0252 /*@}*/
0253
0254 #endif /* _FSL_BEE_H_ */