1 /*
2  * Copyright (c) 2022-2024, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 #ifndef __SIC_BOOT_H__
9 #define __SIC_BOOT_H__
10 
11 #include <stdint.h>
12 
13 #include "rse_kmu_slot_ids.h"
14 #include "boot_hal.h"
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 #ifndef SIC_BOOT_ERR_BASE
21 #define SIC_BOOT_ERR_BASE   0x40000000
22 #endif /* !SIC_BOOT_ERR_BASE */
23 
24 enum sic_boot_err_t
25 {
26     SIC_BOOT_SUCCESS = 0,
27     SIC_BOOT_INVALID_REGION = (SIC_BOOT_ERR_BASE + 0x01),
28     SIC_BOOT_INVALID_ALIGNMENT,
29     SIC_BOOT_ERR_AUTH_INIT,
30     SIC_BOOT_ERR_AUTH_SETUP,
31     SIC_BOOT_ERR_DECR_INIT,
32     SIC_BOOT_ERR_DECR_SETUP,
33     SIC_BOOT_ERR_DECRKEY_EX,
34     SIC_BOOT_ERR_ENABLE,
35 };
36 
37 /**
38  * \brief                  Initialise Secure I-Cache, and begin configuration.
39  *
40  * \return                 sic_boot_err_t
41  */
42 enum sic_boot_err_t sic_boot_init(void);
43 
44 /**
45  * \brief               Setup SIC Authentication and Decryption engines for a
46  *                      firmware image in SIC address space.
47  * \note                Assumes that the XIP firmware image is already mapped
48  *                      to SIC region by the ATU.
49  * \param[in] sictbl    XIP table address.
50  * \param[in] img_addr  Address of firmware image in Secure I-Cache region.
51  * \param[in] img_size  Size of firmware image in Secure I-Cache region.
52  * \param[in] key       Key slot to use for decryption \ref{rse_kmu_slot_ids.h}.
53  * \return              sic_boot_err_t
54  */
55 enum sic_boot_err_t sic_boot_setup_auth_and_decrypt(uintptr_t sictbl,
56                                     uintptr_t img_addr,
57                                     size_t img_size,
58                                     uint8_t region_idx,
59                                     enum rse_kmu_slot_id_t key);
60 
61 /**
62  * \brief           Enable Secure I-cache Athentication and Decryption engine.
63  *
64  * \return          sic_boot_err_t
65  */
66 enum sic_boot_err_t sic_boot_enable_auth_and_decrypt(void);
67 
68 #ifdef RSE_USE_HOST_FLASH /* unchanged for compatibility */
69 
70 /**
71  * \brief                        Perform post-image-load steps to setup SIC,
72  *                               for a given image.
73  *
74  * \param[in]  image_id          The image id to setup the SIC for.
75  * \param[in]  image_load_offset The flash offset the image was loaded from.
76  *                               This is used to detect which of the primary /
77  *                               secondary images was loaded and determine which
78  *                               code should be run through the SIC.
79  *
80  * \return                       sic_boot_err_t
81  */
82 enum sic_boot_err_t sic_boot_post_load(uint32_t image_id, uint32_t image_load_offset);
83 
84 /**
85  * \brief                  Perform SIC configuration that needs to be run just
86  *                         before the bootloader is exited to jump to the new
87  *                         image.
88  *
89  * \param[out] vt_cpy      A pointer to the vector table pointer that is to be
90  *                         jumped to. This is updated to the correct address
91  *                         where the image can be executed via the SIC.
92  *
93  * \return                 sic_boot_err_t
94  */
95 enum sic_boot_err_t sic_boot_pre_quit(struct boot_arm_vector_table **vt_cpy);
96 
97 #endif /* RSE_USE_HOST_FLASH */
98 
99 #ifdef __cplusplus
100 }
101 #endif
102 
103 #endif /* __SIC_BOOT_H__ */
104