Line data Source code
1 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 0 : struct flash_img_context {
33 0 : uint8_t buf[CONFIG_IMG_BLOCK_BUF_SIZE];
34 0 : const struct flash_area *flash_area;
35 0 : 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 1 : struct flash_img_check {
45 0 : const uint8_t *match; /** Match vector data */
46 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : int flash_img_check(struct flash_img_context *ctx,
111 : const struct flash_img_check *fic,
112 : uint8_t area_id);
113 :
114 : /**
115 : * @brief Get the flash area id for the image upload slot.
116 : *
117 : * @return flash area id for the image upload slot
118 : */
119 1 : uint8_t flash_img_get_upload_slot(void);
120 :
121 : #ifdef __cplusplus
122 : }
123 : #endif
124 :
125 : /**
126 : * @}
127 : */
128 :
129 : #endif /* ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_ */
|
