1 /* 2 * Copyright (c) 2019-2024, Arm Limited. All rights reserved. 3 * Copyright (c) 2020 STMicroelectronics. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 */ 8 9 #ifndef __BOOT_HAL_H__ 10 #define __BOOT_HAL_H__ 11 12 #include <stdint.h> 13 #include <stddef.h> 14 #include <stdbool.h> 15 #include "cmsis_compiler.h" 16 17 /* Include header section */ 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 struct boot_arm_vector_table { 24 uint32_t msp; 25 uint32_t reset; 26 }; 27 28 /* 29 * \brief It clears that part of the RAM which was used by MCUBoot, expect the 30 * TFM_SHARED_DATA area, which is used to pass data to the TF-M runtime. 31 * 32 * \note This function must be implemented per target platform by system 33 * integrator. If the bootloader has not loaded any secret to the shared 34 * RAM then this function can immediately return to shorten the boot-up 35 * time. Clearing RAM area can be done several way, it is platform 36 * dependent: 37 * - Overwritten with a pre-defined constant value (i.e.: 0). 38 * - Overwritten with a random value. 39 * - Change the secret if its location is known. 40 * - Set a register which can hide some part of the flash/RAM against 41 * next stage software components. 42 * - Etc. 43 */ 44 void boot_clear_ram_area(void); 45 46 /* 47 * \brief Chain-loading the next image in the boot sequence. 48 * Can be overridden for platform specific initialization. 49 * \param[in] reset_handler_addr Address of next image's Reset_Handler() in 50 the boot chain (TF-M SPE, etc.) 51 */ 52 __NO_RETURN void boot_jump_to_next_image(uint32_t reset_handler_addr); 53 54 /** 55 * \brief Platform peripherals and devices initialization. 56 * Can be overridden for platform specific initialization. 57 * 58 * \return Returns 0 on success, non-zero otherwise 59 */ 60 int32_t boot_platform_init(void); 61 62 /** 63 * \brief Perform later platform specific initialization. Runs at the end of the 64 * boot initialization phase, for platform-specific code that depends on 65 * other initialization code being run beforehand. 66 * 67 * \return Returns 0 on success, non-zero otherwise 68 */ 69 int32_t boot_platform_post_init(void); 70 71 /** 72 * \brief Platform operation to start secure image. 73 * Can be overridden for platform specific initialization. 74 * 75 * \param[in] vt pointer to secure application vector table descriptor 76 */ 77 __NO_RETURN void boot_platform_quit(struct boot_arm_vector_table *vt); 78 79 /** 80 * \brief Platform operation to perform steps required before image load. 81 * Can be overridden for platform specific initialization. 82 * 83 * \param[in] image_id The ID of the image that is about to be loaded. 84 * 85 * \return Returns 0 on success, non-zero otherwise 86 */ 87 int boot_platform_pre_load(uint32_t image_id); 88 89 /** 90 * \brief Platform operation to perform steps required after image load. 91 * Can be overridden for platform specific initialization. 92 * 93 * \param[in] image_id The ID of the image that has just been loaded. 94 * 95 * \return Returns 0 on success, non-zero otherwise 96 */ 97 int boot_platform_post_load(uint32_t image_id); 98 99 /** 100 * \brief Platform operation to check if a particular image should be loaded. 101 * 102 * \param[in] image_id The ID of the image that is being queried. 103 * 104 * \return Returns true if image should be loaded, false otherwise 105 */ 106 bool boot_platform_should_load_image(uint32_t image_id); 107 108 /** 109 * Version of a SW component, to be encoded as "major.minor.revision+build_num". 110 */ 111 struct boot_measurement_version { 112 uint8_t major; 113 uint8_t minor; 114 uint16_t revision; 115 uint32_t build_num; 116 }; 117 118 struct boot_measurement_metadata { 119 uint32_t measurement_type; /* Identifier of the measurement method 120 * used to compute the measurement value. 121 */ 122 uint8_t signer_id[64]; /* Signer identity (hash of public key). */ 123 size_t signer_id_size; /* Size of the signer's ID in bytes. */ 124 char sw_type[10]; /* Representing the role of the SW component. */ 125 struct boot_measurement_version sw_version; /* Version of the SW component */ 126 }; 127 128 /** 129 * \brief Stores single boot measurement and associated metadata in a 130 * non-persistent storage to a known location. 131 * 132 * \note The measurement values and associated metadata are stored at a known 133 * location where they can be accessed later at runtime from secure 134 * software. 135 * 136 * \param[in] index In which measurement slot to store, 137 * the largest allowed index is 63 (0x3F). 138 * \param[in] measurement Pointer to buffer that stores the 139 * measurement value. 140 * \param[in] measurement_size Size of the measurement value in bytes. 141 * \param[in] metadata Pointer to a structure, containing the 142 * associated metadata. 143 * \param[in] lock_measurement If true, it locks the measurement slot and 144 * it is not allowed the extend it anymore with 145 * additional measurement values. 146 * 147 * \return Returns 0 on success, non-zero otherwise. 148 */ 149 int boot_store_measurement(uint8_t index, 150 const uint8_t *measurement, 151 size_t measurement_size, 152 const struct boot_measurement_metadata *metadata, 153 bool lock_measurement); 154 155 /** 156 * \brief Run when boot has failed to load any images. Allows for a 157 * platform-specific response. 158 * 159 * \note Care must be taken when implementing this function that it preserves 160 * the security of the secure-boot chain. 161 * 162 * \param[in] image_id The ID of the image that failed to validate. 163 * 164 * \return Returns zero if recovery succeeded, non-zero otherwise. 165 */ 166 int boot_initiate_recovery_mode(uint32_t image_id); 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif /* __BOOT_HAL_H__ */ 173
