1 /* 2 * Copyright (c) 2017 Nordic Semiconductor ASA 3 * Copyright (c) 2017 Linaro Limited 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** 9 * @file 10 * @brief Flash image header file 11 * 12 * This header file declares prototypes for the flash image APIs used for DFU. 13 */ 14 15 #ifndef ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_ 16 #define ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_ 17 18 #include <zephyr/storage/stream_flash.h> 19 20 /** 21 * @brief Abstraction layer to write firmware images to flash 22 * 23 * @defgroup flash_img_api Flash image API 24 * @ingroup os_services 25 * @{ 26 */ 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 struct flash_img_context { 33 uint8_t buf[CONFIG_IMG_BLOCK_BUF_SIZE]; 34 const struct flash_area *flash_area; 35 struct stream_flash_ctx stream; 36 }; 37 38 /** 39 * @brief Structure for verify flash region integrity 40 * 41 * Match vector length is fixed and depends on size from hash algorithm used 42 * to verify flash integrity. The current available algorithm is SHA-256. 43 */ 44 struct flash_img_check { 45 const uint8_t *match; /** Match vector data */ 46 size_t clen; /** Content to be compared */ 47 }; 48 49 /** 50 * @brief Initialize context needed for writing the image to the flash. 51 * 52 * @param ctx context to be initialized 53 * @param area_id flash area id of partition where the image should be written 54 * 55 * @return 0 on success, negative errno code on fail 56 */ 57 int flash_img_init_id(struct flash_img_context *ctx, uint8_t area_id); 58 59 /** 60 * @brief Initialize context needed for writing the image to the flash. 61 * 62 * @param ctx context to be initialized 63 * 64 * @return 0 on success, negative errno code on fail 65 */ 66 int flash_img_init(struct flash_img_context *ctx); 67 68 /** 69 * @brief Read number of bytes of the image written to the flash. 70 * 71 * @param ctx context 72 * 73 * @return Number of bytes written to the image flash. 74 */ 75 size_t flash_img_bytes_written(struct flash_img_context *ctx); 76 77 /** 78 * @brief Process input buffers to be written to the image slot 1. flash 79 * memory in single blocks. Will store remainder between calls. 80 * 81 * A final call to this function with flush set to true 82 * will write out the remaining block buffer to flash. Since flash is written to 83 * in blocks, the contents of flash from the last byte written up to the next 84 * multiple of CONFIG_IMG_BLOCK_BUF_SIZE is padded with 0xff. 85 * 86 * @param ctx context 87 * @param data data to write 88 * @param len Number of bytes to write 89 * @param flush when true this forces any buffered 90 * data to be written to flash 91 * 92 * @return 0 on success, negative errno code on fail 93 */ 94 int flash_img_buffered_write(struct flash_img_context *ctx, const uint8_t *data, 95 size_t len, bool flush); 96 97 /** 98 * @brief Verify flash memory length bytes integrity from a flash area. The 99 * start point is indicated by an offset value. 100 * 101 * The function is enabled via CONFIG_IMG_ENABLE_IMAGE_CHECK Kconfig options. 102 * 103 * @param[in] ctx context. 104 * @param[in] fic flash img check data. 105 * @param[in] area_id flash area id of partition where the image should be 106 * verified. 107 * 108 * @return 0 on success, negative errno code on fail 109 */ 110 int flash_img_check(struct flash_img_context *ctx, 111 const struct flash_img_check *fic, 112 uint8_t area_id); 113 114 #ifdef __cplusplus 115 } 116 #endif 117 118 /** 119 * @} 120 */ 121 122 #endif /* ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_ */ 123
