1 /*
2 * Copyright 2017, 2019 NXP
3 * All rights reserved.
4 *
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 */
8
9 #ifndef _FSL_BEE_H_
10 #define _FSL_BEE_H_
11
12 #include "fsl_common.h"
13
14 /*!
15 * @addtogroup bee
16 * @{
17 */
18
19 /*******************************************************************************
20 * Definitions
21 *******************************************************************************/
22
23 /*! @name Driver version */
24 /*@{*/
25 /*! @brief BEE driver version. Version 2.0.2.
26 *
27 * Current version: 2.0.2
28 *
29 * Change log:
30 *
31 * - 2.0.2
32 * - Bug Fixes
33 * - Fixed MISRA issue.
34 *
35 * - 2.0.1
36 * - Bug Fixes
37 * - Fixed bug in key user key loading sequence. BEE must be enabled during loading of user key.
38 * - Fixed typos in comments.
39 * - New Features
40 * - Added configuration setting for endian swap, access permission and region security level.
41 * - Improvements
42 * - Setting of AES nonce was moved from BEE_SetRegionKey() into separate BEE_SetRegionNonce() function.
43 * - Changed handling of region settings. Both regions are configured simultaneously by BEE_SetConfig() function.
44 * Configuration of FAC start and end address using IOMUXC_GPRs was moved to application.
45 * - Default value for region address offset was changed to 0.
46 *
47 * - 2.0.0
48 * - Initial version
49 */
50 #define FSL_BEE_DRIVER_VERSION (MAKE_VERSION(2, 0, 2))
51 /*@}*/
52
53 /*! @brief BEE aes mode. */
54 typedef enum _bee_aes_mode
55 {
56 kBEE_AesEcbMode = 0U, /*!< AES ECB Mode */
57 kBEE_AesCtrMode = 1U /*!< AES CTR Mode */
58 } bee_aes_mode_t;
59
60 /*! @brief BEE region. */
61 typedef enum _bee_region
62 {
63 kBEE_Region0 = 0U, /*!< BEE region 0 */
64 kBEE_Region1 = 1U /*!< BEE region 1 */
65 } bee_region_t;
66
67 /*! @brief BEE ac prot enable. */
68 typedef enum _bee_ac_prot_enable
69 {
70 kBEE_AccessProtDisabled = 0U, /*!< BEE access permission control disabled */
71 kBEE_AccessProtEnabled = 1U /*!< BEE access permission control enabled */
72 } bee_ac_prot_enable;
73
74 /*! @brief BEE endian swap enable. */
75 typedef enum _bee_endian_swap_enable
76 {
77 kBEE_EndianSwapDisabled = 1U, /*!< BEE endian swap disabled */
78 kBEE_EndianSwapEnabled = 0U /*!< BEE endian swap enabled */
79 } bee_endian_swap_enable;
80
81 /*! @brief BEE security level. */
82 typedef enum _bee_security_level
83 {
84 kBEE_SecurityLevel0 = 0U, /*!< BEE security level 0 */
85 kBEE_SecurityLevel1 = 1U, /*!< BEE security level 1 */
86 kBEE_SecurityLevel2 = 2U, /*!< BEE security level 2 */
87 kBEE_SecurityLevel3 = 3U /*!< BEE security level 3 */
88 } bee_security_level;
89
90 /*! @brief BEE status flags. */
91 typedef enum _bee_status_flags
92 {
93 kBEE_DisableAbortFlag = 1U, /*!< Disable abort flag. */
94 kBEE_Reg0ReadSecViolation = 2U, /*!< Region-0 read channel security violation */
95 kBEE_ReadIllegalAccess = 4U, /*!< Read channel illegal access detected */
96 kBEE_Reg1ReadSecViolation = 8U, /*!< Region-1 read channel security violation */
97 kBEE_Reg0AccessViolation = 16U, /*!< Protected region-0 access violation */
98 kBEE_Reg1AccessViolation = 32U, /*!< Protected region-1 access violation */
99 kBEE_IdleFlag = BEE_STATUS_BEE_IDLE_MASK /*!< Idle flag */
100 } bee_status_flags_t;
101
102 /*! @brief BEE region configuration structure. */
103 typedef struct _bee_region_config
104 {
105 bee_aes_mode_t region0Mode; /*!< AES mode used for encryption/decryption for region 0 */
106 bee_aes_mode_t region1Mode; /*!< AES mode used for encryption/decryption for region 1 */
107 uint32_t region0AddrOffset; /*!< Region 0 address offset */
108 uint32_t region1AddrOffset; /*!< Region 1 address offset */
109 bee_security_level region0SecLevel; /*!< Region 0 security level */
110 bee_security_level region1SecLevel; /*!< Region 1 security level */
111 uint32_t region1Bot; /*!< Region 1 bottom address */
112 uint32_t region1Top; /*!< Region 1 top address */
113 bee_ac_prot_enable accessPermission; /*!< Access permission control enable/disable */
114 bee_endian_swap_enable endianSwapEn; /*!< Endian swap enable/disable */
115 } bee_region_config_t;
116
117 /*******************************************************************************
118 * API
119 ******************************************************************************/
120 #if defined(__cplusplus)
121 extern "C" {
122 #endif
123
124 /*!
125 * @brief Resets BEE module to factory default values.
126 *
127 * This function performs hardware reset of BEE module. Attributes and keys from software for both regions are cleared.
128 *
129 * @param base BEE peripheral address.
130 */
131 void BEE_Init(BEE_Type *base);
132
133 /*!
134 * @brief Resets BEE module, clears keys for both regions and disables clock to the BEE.
135 *
136 * This function performs hardware reset of BEE module and disables clocks. Attributes and keys from software for both
137 * regions are cleared.
138 *
139 * @param base BEE peripheral address.
140 */
141 void BEE_Deinit(BEE_Type *base);
142
143 /*!
144 * @brief Enables BEE decryption.
145 *
146 * This function enables decryption using BEE.
147 *
148 * @param base BEE peripheral address.
149 */
BEE_Enable(BEE_Type * base)150 static inline void BEE_Enable(BEE_Type *base)
151 {
152 base->CTRL |= BEE_CTRL_BEE_ENABLE_MASK;
153 }
154
155 /*!
156 * @brief Disables BEE decryption.
157 *
158 * This function disables decryption using BEE.
159 *
160 * @param base BEE peripheral address.
161 */
BEE_Disable(BEE_Type * base)162 static inline void BEE_Disable(BEE_Type *base)
163 {
164 base->CTRL &= ~BEE_CTRL_BEE_ENABLE_MASK;
165 }
166
167 /*!
168 * @brief Loads default values to the BEE region configuration structure.
169 *
170 * Loads default values to the BEE region configuration structure. The default values are as follows:
171 * @code
172 * config->region0Mode = kBEE_AesCtrMode;
173 * config->region1Mode = kBEE_AesCtrMode;
174 * config->region0AddrOffset = 0U;
175 * config->region1AddrOffset = 0U;
176 * config->region0SecLevel = kBEE_SecurityLevel3;
177 * config->region1SecLevel = kBEE_SecurityLevel3;
178 * config->region1Bot = 0U;
179 * config->region1Top = 0U;
180 * config->accessPermission = kBEE_AccessProtDisabled;
181 * config->endianSwapEn = kBEE_EndianSwapEnabled;
182 * @endcode
183 *
184 * @param config Configuration structure for BEE peripheral.
185 */
186 void BEE_GetDefaultConfig(bee_region_config_t *config);
187
188 /*!
189 * @brief Sets BEE configuration.
190 *
191 * This function sets BEE peripheral and BEE region settings accorging to given configuration structure.
192 *
193 * @param base BEE peripheral address.
194 * @param config Configuration structure for BEE.
195 */
196 void BEE_SetConfig(BEE_Type *base, const bee_region_config_t *config);
197
198 /*!
199 * @brief Loads the AES key for selected region into BEE key registers.
200 *
201 * This function loads given AES key to BEE register for the given region.
202 * The key must be 32-bit aligned and stored in little-endian format.
203 *
204 * Please note, that eFuse BEE_KEYx_SEL must be set accordingly to be able to load and use key loaded in BEE registers.
205 * Otherwise, key cannot loaded and BEE will use key from OTPMK or SW_GP2.
206 *
207 * @param base BEE peripheral address.
208 * @param region Selection of the BEE region to be configured.
209 * @param key AES key (in little-endian format).
210 * @param keySize Size of AES key.
211 */
212 status_t BEE_SetRegionKey(BEE_Type *base, bee_region_t region, const uint8_t *key, size_t keySize);
213
214 /*!
215 * @brief Loads the nonce for selected region into BEE nonce registers.
216 *
217 * This function loads given nonce(only AES CTR mode) to BEE register for the given region.
218 * The nonce must be 32-bit aligned and stored in little-endian format.
219 *
220 * @param base BEE peripheral address.
221 * @param region Selection of the BEE region to be configured.
222 * @param nonce AES nonce (in little-endian format).
223 * @param nonceSize Size of AES nonce.
224 */
225 status_t BEE_SetRegionNonce(BEE_Type *base, bee_region_t region, const uint8_t *nonce, size_t nonceSize);
226
227 /*!
228 * @brief Gets the BEE status flags.
229 *
230 * This function returns status of BEE peripheral.
231 *
232 * @param base BEE peripheral address.
233 *
234 * @return The status flags. This is the logical OR of members of the
235 * enumeration ::bee_status_flags_t
236 */
237 uint32_t BEE_GetStatusFlags(BEE_Type *base);
238
239 /*!
240 * @brief Clears the BEE status flags.
241 *
242 * @param base BEE peripheral base address.
243 * @param mask The status flags to clear. This is a logical OR of members of the
244 * enumeration ::bee_status_flags_t
245 */
246 void BEE_ClearStatusFlags(BEE_Type *base, uint32_t mask);
247
248 #if defined(__cplusplus)
249 }
250 #endif
251
252 /*@}*/
253
254 #endif /* _FSL_BEE_H_ */
255
