1 /* 2 * SPDX-License-Identifier: Apache-2.0 3 * 4 * Copyright (c) 2021 Nordic Semiconductor ASA 5 * 6 * Original license: 7 * 8 * Licensed to the Apache Software Foundation (ASF) under one 9 * or more contributor license agreements. See the NOTICE file 10 * distributed with this work for additional information 11 * regarding copyright ownership. The ASF licenses this file 12 * to you under the Apache License, Version 2.0 (the 13 * "License"); you may not use this file except in compliance 14 * with the License. You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, 19 * software distributed under the License is distributed on an 20 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 21 * KIND, either express or implied. See the License for the 22 * specific language governing permissions and limitations 23 * under the License. 24 */ 25 26 /** 27 * @file 28 * @brief Hooks definition implementation API 29 * 30 * This file contains API interface definition for hooks which can be 31 * implemented to overide or to amend some of MCUboot's native routines. 32 */ 33 34 #ifndef H_BOOTUTIL_HOOKS 35 #define H_BOOTUTIL_HOOKS 36 37 #ifdef MCUBOOT_IMAGE_ACCESS_HOOKS 38 39 #define BOOT_HOOK_CALL(f, ret_default, ...) f(__VA_ARGS__) 40 41 #define BOOT_HOOK_CALL_FIH(f, fih_ret_default, fih_rc, ...) \ 42 do { \ 43 FIH_CALL(f, fih_rc, __VA_ARGS__); \ 44 } while(0); 45 46 #else 47 48 #define BOOT_HOOK_CALL(f, ret_default, ...) ret_default 49 50 #define BOOT_HOOK_CALL_FIH(f, fih_ret_default, fih_rc, ...) \ 51 do { \ 52 fih_rc = fih_ret_default; \ 53 } while(0); 54 55 #endif 56 57 /** Hook for provide image header data. 58 * 59 * This Hook may be used to overide image header read implementation or doing 60 * a custom action before. 61 * 62 * @param img_index the index of the image pair 63 * @param slot slot number 64 * @param img_head image header structure to be populated 65 * 66 * @retval 0: header was read/populated, skip direct header data read 67 * BOOT_HOOK_REGULAR: follow the normal execution path, 68 * otherwise an error-code value. 69 */ 70 int boot_read_image_header_hook(int img_index, int slot, 71 struct image_header *img_head); 72 73 /** Hook for Validate image hash/signature 74 * 75 * This Hook may be used to overide image validation procedure or doing 76 * a custom action before. 77 * 78 * @param img_index the index of the image pair 79 * @param slot slot number 80 * 81 * @retval FIH_SUCCESS: image is valid, skip direct validation 82 * FIH_FAILURE: image is invalid, skip direct validation 83 * FIH_BOOT_HOOK_REGULAR: follow the normal execution path. 84 */ 85 fih_ret boot_image_check_hook(int img_index, int slot); 86 87 /** Hook for implement image update 88 * 89 * This hook is for for implementing an alternative mechanism of image update or 90 * doing a custom action before. 91 * 92 * @param img_index the index of the image pair 93 * @param img_head the image header of the secondary image 94 * @param area the flash area of the secondary image. 95 * 96 * @retval 0: update was done, skip performing the update 97 * BOOT_HOOK_REGULAR: follow the normal execution path, 98 * otherwise an error-code value. 99 */ 100 int boot_perform_update_hook(int img_index, struct image_header *img_head, 101 const struct flash_area *area); 102 103 /** Hook for implement image's post copying action 104 * 105 * This hook is for implement action which might be done right after image was 106 * copied to the primary slot. This hook is called in MCUBOOT_OVERWRITE_ONLY 107 * mode only. 108 * 109 * @param img_index the index of the image pair 110 * @param area the flash area of the primary image. 111 * @param size size of copied image. 112 * 113 * @retval 0: success, mcuboot will follow normal code execution flow after 114 * execution of this call. 115 * non-zero: an error, mcuboot will return from 116 * boot_copy_image() with error. 117 * Update will be undone so might be resume on the next boot. 118 */ 119 int boot_copy_region_post_hook(int img_index, const struct flash_area *area, 120 size_t size); 121 122 /** Hook for implement image's post recovery upload action 123 * 124 * This hook is for implement action which might be done right after image was 125 * copied to the primary slot. This hook is called in serial recovery upload 126 * operation. 127 * 128 * @param img_index the index of the image pair 129 * @param area the flash area of the primary image. 130 * @param size size of copied image. 131 * 132 * @retval 0: success, mcuboot will follow normal code execution flow after 133 * execution of this call. 134 * non-zero: an error, will be transferred as part of comand response 135 * as "rc" entry. 136 */ 137 int boot_serial_uploaded_hook(int img_index, const struct flash_area *area, 138 size_t size); 139 140 /** Hook for implement the image's slot installation status fetch operation for 141 * the MGMT custom command. 142 * 143 * The image's slot installation status is custom property. It's detailed 144 * definition depends on user implementation. It is only defined that the status 145 * will be set to 0 if this hook not provides another value. 146 * 147 * @param img_index the index of the image pair 148 * @param slot slot number 149 * @param img_install_stat the image installation status to be populated 150 * 151 * @retval 0: the installaton status was fetched successfully, 152 * BOOT_HOOK_REGULAR: follow the normal execution path, status will be 153 * set to 0 154 * otherwise an error-code value. Error-code is ignored, but it is up to 155 * the implementation to reflect this error in img_install_stat. 156 */ 157 int boot_img_install_stat_hook(int image_index, int slot, 158 int *img_install_stat); 159 160 /** Hook will be invoked when boot_serial requests device reset. 161 * The hook may be used to prevent device reset. 162 * 163 * @param force set to true when request tries to force reset. 164 * 165 * @retval 0 when reset should be performed; 166 * BOOT_RESET_REQUEST_HOOK_BUSY when some processing is still in 167 * progress; 168 * BOOT_RESET_REQUEST_HOOK_TIMEOUT internal process timed out; 169 * BOOT_RESET_REQUEST_HOOK_CHECK_FAILED internal code failed to 170 * obtian status; 171 * BOOT_RESET_REQUEST_HOOK_INTERNAL_ERROR unspecified internal 172 * error while checking status. 173 */ 174 int boot_reset_request_hook(bool force); 175 176 #define BOOT_RESET_REQUEST_HOOK_BUSY 1 177 #define BOOT_RESET_REQUEST_HOOK_TIMEOUT 2 178 #define BOOT_RESET_REQUEST_HOOK_CHECK_FAILED 3 179 #define BOOT_RESET_REQUEST_HOOK_INTERNAL_ERROR 4 180 181 #endif /*H_BOOTUTIL_HOOKS*/ 182
