1 /*
2  * Copyright 2024 NXP
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 #ifndef FSL_ROMAPI_IAP_H_
7 #define FSL_ROMAPI_IAP_H_
8 
9 #include <stdlib.h>
10 #include <stdint.h>
11 #include "fsl_common.h"
12 #include "fsl_romapi_nboot.h"
13 #include "fsl_sbloader_v3.h"
14 
15 /*******************************************************************************
16  * Definitions
17  ******************************************************************************/
18 /*! @brief Bootloader status group numbers */
19 #define kStatusGroup_SBLoader (101UL)
20 
21 /*! @brief SB loader status codes.*/
22 enum
23 {
24     kStatusRomLdrSectionOverrun         = MAKE_STATUS(kStatusGroup_SBLoader, 0),
25     kStatusRomLdrSignature              = MAKE_STATUS(kStatusGroup_SBLoader, 1),
26     kStatusRomLdrSectionLength          = MAKE_STATUS(kStatusGroup_SBLoader, 2),
27     kStatusRomLdrEOFReached             = MAKE_STATUS(kStatusGroup_SBLoader, 4),
28     kStatusRomLdrChecksum               = MAKE_STATUS(kStatusGroup_SBLoader, 5),
29     kStatusRomLdrCrc32Error             = MAKE_STATUS(kStatusGroup_SBLoader, 6),
30     kStatusRomLdrUnknownCommand         = MAKE_STATUS(kStatusGroup_SBLoader, 7),
31     kStatusRomLdrIdNotFound             = MAKE_STATUS(kStatusGroup_SBLoader, 8),
32     kStatusRomLdrDataUnderrun           = MAKE_STATUS(kStatusGroup_SBLoader, 9),
33     kStatusRomLdrJumpReturned           = MAKE_STATUS(kStatusGroup_SBLoader, 10),
34     kStatusRomLdrCallFailed             = MAKE_STATUS(kStatusGroup_SBLoader, 11),
35     kStatusRomLdrKeyNotFound            = MAKE_STATUS(kStatusGroup_SBLoader, 12),
36     kStatusRomLdrSecureOnly             = MAKE_STATUS(kStatusGroup_SBLoader, 13),
37     kStatusRomLdrResetReturned          = MAKE_STATUS(kStatusGroup_SBLoader, 14),
38     kStatusRomLdrRollbackBlocked        = MAKE_STATUS(kStatusGroup_SBLoader, 15),
39     kStatusRomLdrInvalidSectionMacCount = MAKE_STATUS(kStatusGroup_SBLoader, 16),
40     kStatusRomLdrUnexpectedCommand      = MAKE_STATUS(kStatusGroup_SBLoader, 17),
41     kStatusRomLdrBadSBKEK               = MAKE_STATUS(kStatusGroup_SBLoader, 18),
42 };
43 
44 /*!@brief API initialization data structure*/
45 typedef struct kb_api_parameter_struct
46 {
47     uint32_t allocStart;
48     uint32_t allocSize;
49 } kp_api_init_param_t;
50 
51 /*!@brief The API context structure */
52 typedef struct api_core_context
53 {
54     uint32_t reserved0[166];
55     ldr_Context_v3_t *sbloaderCtx;
56     nboot_context_t *nbootCtx;
57     uint32_t reserved1[5];
58 } api_core_context_t;
59 
60 /*
61  *!@brief Structure of version property.
62  *
63  */
64 typedef union StandardVersion
65 {
66     struct
67     {
68         uint8_t bugfix; /*!< bugfix version [7:0]*/
69         uint8_t minor;  /*!< minor version [15:8]*/
70         uint8_t major;  /*!< major version [23:16]*/
71         char name;      /*!< name [31:24]*/
72     };
73     uint32_t version;   /*!< combined version numbers*/
74 } standard_version_t;
75 
76 /*! @brief IAP API Interface structure */
77 typedef struct iap_api_interface_struct
78 {
79     standard_version_t version; /*!< IAP API version number. */
80     status_t (*api_init)(api_core_context_t *coreCtx, const kp_api_init_param_t *param);
81     status_t (*api_deinit)(api_core_context_t *coreCtx);
82     const uint32_t reserved[8]; /*!< Reserved */
83     status_t (*sbloader_init)(api_core_context_t *ctx);
84     status_t (*sbloader_pump)(api_core_context_t *ctx, uint8_t *data, uint32_t length);
85     status_t (*sbloader_finalize)(api_core_context_t *ctx);
86 } iap_api_interface_t;
87 
88 /*******************************************************************************
89  * API
90  ******************************************************************************/
91 
92 #if defined(__cplusplus)
93 extern "C" {
94 #endif
95 
96 /*!@brief Get IAP Driver version */
97 uint32_t iap_api_version(void);
98 
99 /*!@brief Initialize the IAP API runtime environment*/
100 status_t iap_api_init(api_core_context_t *coreCtx, const kp_api_init_param_t *param);
101 
102 /*!@brief Deinitialize the IAP API runtime environment*/
103 status_t iap_api_deinit(api_core_context_t *coreCtx);
104 
105 /*!@brief Perform the Sbloader runtime environment initialization */
106 status_t iap_sbloader_init(api_core_context_t *ctx);
107 
108 /*!@brief Handle the SB data stream */
109 status_t iap_sbloader_pump(api_core_context_t *ctx, uint8_t *data, uint32_t length);
110 
111 /*!@brief Finish the sbloader handling */
112 status_t iap_sbloader_finalize(api_core_context_t *ctx);
113 
114 #endif /* FSL_ROMAPI_IAP_H_ */
115