1 /*
2 * Copyright (c) 2016, Freescale Semiconductor, Inc.
3 * Copyright 2017-2021,2023 NXP
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 */
8
9 #ifndef FSL_IEE_H_
10 #define FSL_IEE_H_
11
12 #include "fsl_common.h"
13
14 /*!
15 * @addtogroup iee
16 * @{
17 */
18
19 /*******************************************************************************
20 * Definitions
21 ******************************************************************************/
22
23 /*! @name Driver version */
24 /*@{*/
25 /*! @brief IEE driver version. Version 2.1.1.
26 *
27 * Current version: 2.1.1
28 *
29 * Change log:
30 * - Version 2.0.0
31 * - Initial version
32 * - Version 2.1.0
33 * - Add region lock function IEE_LockRegionConfig() and driver clock control
34 * - Version 2.1.1
35 * - Fixed MISRA issues.
36 * - Version 2.2.0
37 * - Add ELE (EdgeLock Enclave) key provisioning feature.
38 */
39 #define FSL_IEE_DRIVER_VERSION (MAKE_VERSION(2, 1, 1))
40 /*@}*/
41
42 /*! @brief IEE region. */
43 typedef enum _iee_region
44 {
45 kIEE_Region0 = 0U, /*!< IEE region 0 */
46 kIEE_Region1 = 1U, /*!< IEE region 1 */
47 kIEE_Region2 = 2U, /*!< IEE region 2 */
48 kIEE_Region3 = 3U, /*!< IEE region 3 */
49 kIEE_Region4 = 4U, /*!< IEE region 4 */
50 kIEE_Region5 = 5U, /*!< IEE region 5 */
51 kIEE_Region6 = 6U, /*!< IEE region 6 */
52 kIEE_Region7 = 7U /*!< IEE region 7 */
53 } iee_region_t;
54
55 /*! @brief IEE AES enablement/bypass. */
56 typedef enum _iee_aes_bypass
57 {
58 kIEE_AesUseMdField = 0U, /*!< AES encryption/decryption enabled */
59 kIEE_AesBypass = 1U /*!< AES encryption/decryption bypass */
60 } iee_aes_bypass_t;
61
62 /*! @brief IEE AES mode. */
63 typedef enum _iee_aes_mode
64 {
65 kIEE_ModeNone = 0U, /*!< AES NONE mode */
66 kIEE_ModeAesXTS = 1U, /*!< AES XTS mode */
67 kIEE_ModeAesCTRWAddress = 2U, /*!< AES CTR w address binding mode */
68 kIEE_ModeAesCTRWOAddress = 3U, /*!< AES CTR w/o address binding mode */
69 kIEE_ModeAesCTRkeystream = 4U /*!< AES CTR keystream only */
70 } iee_aes_mode_t;
71
72 /*! @brief IEE AES key size. */
73 typedef enum _iee_aes_key_size
74 {
75 kIEE_AesCTR128XTS256 = 0U, /*!< AES 128 bits (CTR), 256 bits (XTS) */
76 kIEE_AesCTR256XTS512 = 1U /*!< AES 256 bits (CTR), 512 bits (XTS) */
77 } iee_aes_key_size_t;
78
79 /*! @brief IEE AES key number. */
80 typedef enum _iee_aes_key_num
81 {
82 kIEE_AesKey1 = 1U, /*!< AES Key 1 */
83 kIEE_AesKey2 = 2U /*!< AES Key 2 */
84 } iee_aes_key_num_t;
85
86 /*! @brief IEE configuration structure. */
87 typedef struct _iee_config
88 {
89 iee_aes_bypass_t bypass; /*!< AES encryption/decryption bypass */
90 iee_aes_mode_t mode; /*!< AES mode */
91 iee_aes_key_size_t keySize; /*!< size of AES key */
92 uint32_t pageOffset; /*!< Offset to physical memory location from IEE start address */
93 } iee_config_t;
94
95 /*******************************************************************************
96 * API
97 ******************************************************************************/
98 #if defined(__cplusplus)
99 extern "C" {
100 #endif
101
102 /*!
103 * @brief Resets IEE module to factory default values.
104 *
105 * This function performs hardware reset of IEE module. Attributes and keys of all regions are cleared.
106 *
107 * @param base IEER peripheral address.
108 */
109 void IEE_Init(IEE_Type *base);
110
111 /*!
112 * @brief Loads default values to the IEE configuration structure.
113 *
114 * Loads default values to the IEE region configuration structure. The default values are as follows.
115 * @code
116 * config->bypass = kIEE_AesUseMdField;
117 * config->mode = kIEE_ModeNone;
118 * config->keySize = kIEE_AesCTR128XTS256;
119 * config->pageOffset = 0U;
120 * @endcode
121 *
122 * @param config Configuration for the selected IEE region.
123 */
124 void IEE_GetDefaultConfig(iee_config_t *config);
125
126 /*!
127 * @brief Sets the IEE module according to the configuration structure.
128 *
129 * This function configures IEE region according to configuration structure.
130 *
131 * @param base IEE peripheral address.
132 * @param region Selection of the IEE region to be configured.
133 * @param config Configuration for the selected IEE region.
134 */
135 void IEE_SetRegionConfig(IEE_Type *base, iee_region_t region, iee_config_t *config);
136
137 /*!
138 * @brief Sets the IEE module key.
139 *
140 * This function sets specified AES key for the given region.
141 *
142 * @param base IEE peripheral address.
143 * @param region Selection of the IEE region to be configured.
144 * @param keyNum Selection of AES KEY1 or KEY2.
145 * @param key AES key.
146 * @param keySize Size of AES key.
147 */
148 status_t IEE_SetRegionKey(
149 IEE_Type *base, iee_region_t region, iee_aes_key_num_t keyNum, const uint8_t *key, size_t keySize);
150
151 /*!
152 * @brief Computes IEE offset to be set for specifed memory location.
153 *
154 * This function calculates offset that must be set for IEE region to access physical memory location.
155 *
156 * @param addressIee Address of IEE peripheral.
157 * @param addressMemory Address of physical memory location.
158 */
IEE_GetOffset(uint32_t addressIee,uint32_t addressMemory)159 static inline uint32_t IEE_GetOffset(uint32_t addressIee, uint32_t addressMemory)
160 {
161 return (addressMemory - addressIee) >> 12;
162 }
163
164 /*!
165 * @brief Lock the IEE region configuration.
166 *
167 * This function locks IEE region registers for Key, Offset and Attribute.
168 * Only system reset can clear the Lock bit.
169 *
170 * @param base IEE peripheral address.
171 * @param region Selection of the IEE region to be locked.
172 */
173 void IEE_LockRegionConfig(IEE_Type *base, iee_region_t region);
174
175 #if defined(__cplusplus)
176 }
177 #endif
178
179 /*!
180 *@}
181 */
182
183 #endif /* FSL_IEE_H_ */
184
