1 /* 2 * Copyright (c) 2021-2022, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __TFM_BOOTLOADER_FWU_ABSTRACTION_H__ 9 #define __TFM_BOOTLOADER_FWU_ABSTRACTION_H__ 10 11 #include "stdbool.h" 12 #include "psa/update.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * Bootloader related initialization for firmware update, such as reading 20 * some necessary shared data from the memory if needed. 21 * 22 * \return PSA_SUCCESS On success 23 * PSA_ERROR_GENERIC_ERROR On failure 24 */ 25 psa_status_t fwu_bootloader_init(void); 26 27 /** 28 * \brief Initialize the staging area of the component. 29 * 30 * The component is in READY state. Prepare the staging area of the component 31 * for image download. 32 * For example, initialize the staging area, open the flash area, and so on. 33 * The image will be written into the staging area later. 34 * 35 * \param[in] component The identifier of the target component in bootloader. 36 * \param[in] manifest A pointer to a buffer containing a detached manifest for 37 * the update. If the manifest is bundled with the firmware 38 * image, manifest must be NULL. 39 * \param[in] manifest_size Size of the manifest buffer in bytes. 40 * 41 * \return PSA_SUCCESS On success 42 * PSA_ERROR_INVALID_SIGNATURE A signature or integrity check on the 43 * manifest has failed. 44 * PSA_ERROR_INVALID_ARGUMENT Invalid input parameter 45 * PSA_ERROR_INSUFFICIENT_MEMORY 46 * PSA_ERROR_INSUFFICIENT_STORAGE 47 * PSA_ERROR_COMMUNICATION_FAILURE 48 * PSA_ERROR_STORAGE_FAILURE 49 * 50 */ 51 psa_status_t fwu_bootloader_staging_area_init(psa_fwu_component_t component, 52 const void *manifest, 53 size_t manifest_size); 54 55 /** 56 * \brief Load the image into the target component. 57 * 58 * The component is in WRITING state. Write the image data into the target 59 * component. 60 * 61 * \param[in] component The identifier of the target component in bootloader. 62 * \param[in] image_offset The offset of the image being passed into block, in 63 * bytes 64 * \param[in] block A buffer containing a block of image data. This 65 * might be a complete image or a subset. 66 * \param[in] block_size Size of block. 67 * 68 * \return PSA_SUCCESS On success 69 * PSA_ERROR_INVALID_ARGUMENT Invalid input parameter 70 * PSA_ERROR_INSUFFICIENT_MEMORY There is no enough memory to 71 * process the update 72 * PSA_ERROR_INSUFFICIENT_STORAGE There is no enough storage to 73 * process the update 74 * PSA_ERROR_GENERIC_ERROR A fatal error occurred 75 * 76 */ 77 psa_status_t fwu_bootloader_load_image(psa_fwu_component_t component, 78 size_t image_offset, 79 const void *block, 80 size_t block_size); 81 82 /** 83 * \brief Starts the installation of an image. 84 * 85 * The components are in CANDIDATE state. Check the authenticity and integrity of 86 * the staged image in the components. If a reboot is required to complete the 87 * check, then mark this image as a candidate so that the next time bootloader 88 * runs it will take this image as a candidate one to boot-up. Return the error 89 * code PSA_SUCCESS_REBOOT. 90 * 91 * \param[in] candidates A list of components in CANDIDATE state. 92 * \param[in] number Number of components in CANDIDATE state. 93 * 94 * \return PSA_SUCCESS On success 95 * PSA_SUCCESS_REBOOT A system reboot is needed to finish installation 96 * TFM_SUCCESS_RESTART A restart of the updated component is required 97 * to complete the update 98 * PSA_ERROR_DEPENDENCY_NEEDED Another image needs to be installed to 99 * finish installation 100 * PSA_ERROR_INVALID_ARGUMENT Invalid input parameter 101 * PSA_ERROR_INVALID_SIGNATURE The signature is incorrect 102 * PSA_ERROR_GENERIC_ERROR A fatal error occurred 103 * TFM_ERROR_ROLLBACK_DETECTED The image is too old to be installed. 104 * If the image metadata contains a 105 * timestamp and it has expired, then 106 * this error is also returned. 107 */ 108 psa_status_t fwu_bootloader_install_image(const psa_fwu_component_t *candidates, 109 uint8_t number); 110 111 /** 112 * \brief Mark the TRIAL(running) image in component as confirmed. 113 * 114 * Call this API to mark the running images as permanent/accepted to avoid 115 * revert when next time boot-up. Usually, this API is called after the running 116 * images have been verified as valid. 117 * 118 * \param[in] trials A list of components in TRIAL state. 119 * \param[in] number Number of components in TRIAL state. 120 * 121 * \return PSA_SUCCESS On success 122 * PSA_ERROR_INSUFFICIENT_MEMORY 123 * PSA_ERROR_INSUFFICIENT_STORAGE 124 * PSA_ERROR_COMMUNICATION_FAILURE 125 * PSA_ERROR_STORAGE_FAILURE 126 */ 127 psa_status_t fwu_bootloader_mark_image_accepted(const psa_fwu_component_t *trials, 128 uint8_t number); 129 130 /** 131 * \brief Uninstall the staged image in the component. 132 * 133 * The component is in STAGED state. Uninstall the staged image in the component 134 * so that this image will not be treated as a candidate next time boot-up. 135 * 136 * \param[in] component The identifier of the target component. 137 * 138 * \return PSA_SUCCESS On success 139 * PSA_ERROR_INSUFFICIENT_MEMORY 140 * PSA_ERROR_INSUFFICIENT_STORAGE 141 * PSA_ERROR_COMMUNICATION_FAILURE 142 * PSA_ERROR_STORAGE_FAILURE 143 */ 144 psa_status_t fwu_bootloader_reject_staged_image(psa_fwu_component_t component); 145 146 /** 147 * \brief Reject the trial image in the component. 148 * 149 * The component is in TRIAL state. Mark the running image in the component as 150 * rejected. 151 * 152 * \param[in] component The identifier of the target component. 153 * 154 * \return PSA_SUCCESS On success 155 * PSA_ERROR_INSUFFICIENT_MEMORY 156 * PSA_ERROR_INSUFFICIENT_STORAGE 157 * PSA_ERROR_COMMUNICATION_FAILURE 158 * PSA_ERROR_STORAGE_FAILURE 159 */ 160 psa_status_t fwu_bootloader_reject_trial_image(psa_fwu_component_t component); 161 162 /** 163 * \brief The component is in FAILED or UPDATED state. Clean the staging area of the component. 164 * 165 * \param[in] component The identifier of the target component. 166 * 167 * \return PSA_SUCCESS On success 168 * PSA_ERROR_INVALID_ARGUMENT Invalid input parameter 169 * PSA_ERROR_STORAGE_FAILURE 170 */ 171 psa_status_t fwu_bootloader_clean_component(psa_fwu_component_t component); 172 173 /** 174 * \brief Get the image information. 175 * 176 * Get the image information of the given component in staging area 177 * or the running area. 178 * 179 * \param[in] component The identifier of the target component in bootloader. 180 * \param[in] query_state Query 'state' field. 181 * \param[in] query_impl_info Query 'impl' field. 182 * \param[out] info Buffer containing return the component information. 183 184 * \return PSA_SUCCESS On success 185 * PSA_ERROR_INVALID_ARGUMENT Invalid input parameter 186 * PSA_ERROR_GENERIC_ERROR A fatal error occurred 187 */ 188 psa_status_t fwu_bootloader_get_image_info(psa_fwu_component_t component, 189 bool query_state, 190 bool query_impl_info, 191 psa_fwu_component_info_t *info); 192 #ifdef __cplusplus 193 } 194 #endif 195 #endif /* __TFM_BOOTLOADER_FWU_ABSTRACTION_H__ */ 196