1 /*
2  * Copyright 2022,2024 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 #ifndef _FSL_ROMAPI_IAP_H_
8 #define _FSL_ROMAPI_IAP_H_
9 
10 #include <stdlib.h>
11 #include <stdint.h>
12 #include "fsl_common.h"
13 #include "fsl_romapi_flexspi.h"
14 #include "fsl_romapi_nboot.h"
15 #include "fsl_kb_api.h"
16 #include "fsl_sbloader_v3.h"
17 
18 /*******************************************************************************
19  * Definitions
20  ******************************************************************************/
21 #define API_GROUP (1000UL)
22 
23 //! @brief Memory Interface count
24 #define MEM_INTERFACE_COUNT (2U)
25 
26 /*******************************************************************************
27  *
28  *      Memory Identifier definitions
29  *
30  * *****************************************************************************/
31 #define kMemoryID_Internal   (0x0U)      //!< Internal FLASH/RAM ID
32 #define kMemoryID_FlexspiNor (0x9U)      //!< FlexSPI NOR ID
33 #define MEMORY_GROUP(id)     ((id) >> 8) //!< Get the Memory group
34 
35 /* Memory belongs to internal memory space (addressable) */
36 #define kMemoryGroup_Internal (0U)
37 /* Memory belongs to external memory space (non-addressable) */
38 #define kMemoryGroup_External (1U)
39 
40 //! @brief Contiguous RAM region count
41 #define RAM_REGION_COUNT (2U)
42 
43 //! @brief Contiguous FLEXSPINOR meomry count
44 #define FLEXSPINOR_REGION_COUNT (1U)
45 
46 /*! @brief iap version for ROM*/
47 enum iap_version_constants
48 {
49     kIAP_VersionName   = 'I', /*!< IAP version name.*/
50     kIAP_VersionMajor  = 1,   /*!< Major IAP version.*/
51     kIAP_VersionMinor  = 0,   /*!< Minor IAP version.*/
52     kIAP_VersionBugfix = 0    /*!< Bugfix for IAP version.*/
53 };
54 
55 //!@brief ROM API status definitions
56 enum
57 {
58     //!< IAP API execution succedded
59     kStatus_IAP_Success = kStatus_Success,
60     //!< IAP API exeution failed
61     kStatus_IAP_Fail = kStatus_Fail,
62     //!< Invalid argument detected during API execution
63     kStatus_IAP_InvalidArgument = MAKE_STATUS(API_GROUP, 1U),
64     //!< The Heap size is not enough during API execution
65     kStatus_IAP_OutOfMemory = MAKE_STATUS(API_GROUP, 2U),
66     //!< The read memory operation is disallowed during API execution
67     kStatus_IAP_ReadDisallowed = MAKE_STATUS(API_GROUP, 3U),
68     //!< The FLASH region to be programmed is not empty
69     kStatus_IAP_CumulativeWrite = MAKE_STATUS(API_GROUP, 4U),
70     //!< Erase operation failed
71     kStatus_IAP_EraseFailure = MAKE_STATUS(API_GROUP, 5U),
72     //!< The specific command is not supported
73     kStatus_IAP_CommandNotSupported = MAKE_STATUS(API_GROUP, 6U),
74     //!< Memory access is disabled, typically occurred on the FLEXSPI NOR if it is not configured properly
75     kStatus_IAP_MemoryAccessDisabled = MAKE_STATUS(API_GROUP, 7U),
76 };
77 
78 typedef struct _arena_context
79 {
80     uint32_t start_1;
81     uint32_t end_1;
82     uint32_t nextAddr;
83 } arena_context_t;
84 
85 //!@brief Memory region information table
86 typedef struct mem_region
87 {
88     uint32_t start_2;
89     uint32_t end_2;
90 } mem_region_t;
91 
92 //! @brief Memory Attribute Structure
93 typedef struct _mem_attribute
94 {
95     uint32_t memId;
96     uint32_t regionCount;
97     mem_region_t *memRegions;
98     void *context;
99 } mem_attribute_t;
100 
101 //!@brief Memory region interface structure
102 typedef struct api_memory_region_interface
103 {
104     status_t (*init)(mem_attribute_t *attr);
105 #if defined(ROM_API_HAS_FEATURE_MEM_READ) && (ROM_API_HAS_FEATURE_MEM_READ == 1u)
106     status_t (*read)(mem_attribute_t *attr, uint32_t addr, uint32_t leth, uint8_t *buf);
107 #endif
108     status_t (*write)(mem_attribute_t *attr, uint32_t addr, uint32_t len, const uint8_t *buf);
109     status_t (*fill)(mem_attribute_t *attr, uint32_t addr, uint32_t len, uint32_t pattern);
110     status_t (*flush)(mem_attribute_t *attr);
111     status_t (*erase)(mem_attribute_t *attr, uint32_t addr, uint32_t const len);
112     status_t (*config)(mem_attribute_t *attr, uint32_t *buf);
113     status_t (*erase_all)(mem_attribute_t *attr);
114     status_t (*alloc_ctx)(arena_context_t *ctx, mem_attribute_t *attr, void *miscParams);
115 } api_memory_region_interface_t;
116 
117 //!@brief Memory entry data structure
118 typedef struct memory_map_entry
119 {
120     mem_attribute_t *memoryAttribute;
121     const api_memory_region_interface_t *memoryInterface;
122 } api_memory_map_entry_t;
123 //!@brief API initialization data structure
124 typedef struct kb_api_parameter_struct
125 {
126     uint32_t allocStart;
127     uint32_t allocSize;
128 } kp_api_init_param_t;
129 
130 //!@brief Memory context structure
131 typedef struct memory_context_struct
132 {
133     status_t (*flush)(mem_attribute_t *attr);
134     mem_attribute_t *attr;
135 } mem_context_t;
136 
137 typedef struct soc_memory_map_struct
138 {
139     struct
140     {
141         uint32_t starts;
142         uint32_t ends;
143     } ramRegions[RAM_REGION_COUNT];
144     struct
145     {
146         uint32_t starts_1;
147         uint32_t ends_1;
148     } flexspiNorRegions[FLEXSPINOR_REGION_COUNT];
149 } soc_mem_regions_t;
150 
151 //!@brief The API context structure
152 typedef struct api_core_context
153 {
154     soc_mem_regions_t memRegions;
155     arena_context_t arenaCtx;
156     flexspi_nor_config_t flexspinorCfg;
157     mem_context_t memCtx;
158     ldr_Context_v3_t *sbloaderCtx;
159     nboot_context_t *nbootCtx;
160     uint8_t *sharedBuf;
161     api_memory_map_entry_t memEntries[MEM_INTERFACE_COUNT];
162 } api_core_context_t;
163 
164 /*
165  *!@brief Structure of version property.
166  *
167  */
168 typedef union StandardVersion
169 {
170     struct
171     {
172         uint8_t bugfix; //!< bugfix version [7:0]
173         uint8_t minor;  //!< minor version [15:8]
174         uint8_t major;  //!< major version [23:16]
175         char name;      //!< name [31:24]
176     };
177     uint32_t version; //!< combined version numbers
178 } standard_version_t;
179 
180 //!@brief IAP API Interface structure
181 typedef struct iap_api_interface_struct
182 {
183     standard_version_t version; //!< IAP API version number.
184     status_t (*api_init)(api_core_context_t *coreCtx, const kp_api_init_param_t *param);
185     status_t (*api_deinit)(api_core_context_t *coreCtx);
186     status_t (*mem_init_api)(api_core_context_t *ctx);
187     status_t (*mem_read)(api_core_context_t *ctx, uint32_t addr, uint32_t len, uint8_t *buf, uint32_t memoryId);
188     status_t (*mem_write)(api_core_context_t *ctx, uint32_t addr, uint32_t len, const uint8_t *buf, uint32_t memoryId);
189     status_t (*mem_fill)(api_core_context_t *ctx, uint32_t addr, uint32_t len, uint32_t pattern, uint32_t memoryId);
190     status_t (*mem_flush)(api_core_context_t *ctx);
191     status_t (*mem_erase)(api_core_context_t *ctx, uint32_t addr, uint32_t len, uint32_t memoryId);
192     status_t (*mem_config)(api_core_context_t *ctx, uint32_t *buf, uint32_t memoryId);
193     status_t (*mem_erase_all)(api_core_context_t *ctx, uint32_t memoryId);
194     status_t (*sbloader_init)(api_core_context_t *ctx);
195     status_t (*sbloader_pump)(api_core_context_t *ctx, const uint8_t *data, uint32_t length);
196     status_t (*sbloader_finalize)(api_core_context_t *ctx);
197 } iap_api_interface_t;
198 
199 /*******************************************************************************
200  * API
201  ******************************************************************************/
202 
203 #if defined(__cplusplus)
204 extern "C" {
205 #endif
206 
207 //!@brief Get IAP Driver version
208 uint32_t iap_api_version(void);
209 
210 //!@brief Initialize the IAP API runtime environment
211 status_t iap_api_init(api_core_context_t *coreCtx, const kp_api_init_param_t *param);
212 
213 //!@brief Deinitialize the IAP API runtime environment
214 status_t iap_api_deinit(api_core_context_t *coreCtx);
215 
216 //!@brief Intialize the memory interface of the IAP API
217 status_t iap_mem_init(api_core_context_t *coreCtx);
218 
219 //!@brief Perform the memory write operation
220 status_t iap_mem_write(
221     api_core_context_t *coreCtx, uint32_t start, uint32_t lengthInBytes, const uint8_t *buf, uint32_t memoryId);
222 
223 //!@brief Perform the Memory read operation
224 status_t iap_mem_read(
225     api_core_context_t *coreCtx, uint32_t start, uint32_t lengthInBytes, uint8_t *buf, uint32_t memoryId);
226 
227 //!@brief Perform the Fill operation
228 status_t iap_mem_fill(
229     api_core_context_t *coreCtx, uint32_t start, uint32_t lengthInBytes, uint32_t pattern, uint32_t memoryId);
230 
231 //!@brief Perform the Memory erase operation
232 status_t iap_mem_erase(api_core_context_t *coreCtx, uint32_t start, uint32_t lengthInBytes, uint32_t memoryId);
233 
234 //!@brief Perform the full Memory erase operation for specify MemoryID
235 status_t iap_mem_erase_all(api_core_context_t *coreCtx, uint32_t memoryId);
236 
237 //!@brief Perform the Memory configuration operation
238 status_t iap_mem_config(api_core_context_t *coreCtx, uint32_t *config, uint32_t memoryId);
239 
240 //!@brief Perform the Memory Flush operation
241 status_t iap_mem_flush(api_core_context_t *coreCtx);
242 
243 //!@brief Perform the Sbloader runtime environment initialization
244 status_t iap_sbloader_init(api_core_context_t *ctx);
245 
246 //!@brief Handle the SB data stream
247 status_t iap_sbloader_pump(api_core_context_t *ctx, const uint8_t *data, uint32_t length);
248 
249 //!@brief Finish the sbloader handling
250 status_t iap_sbloader_finalize(api_core_context_t *ctx);
251 
252 #endif /* _FSL_ROMAPI_IAP_H_ */
253