Line data Source code
1 0 : /*
2 : * Copyright (c) 2023 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef H_IMG_MGMT_CLIENT_
8 : #define H_IMG_MGMT_CLIENT_
9 :
10 : #include <inttypes.h>
11 : #include <zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h>
12 : #include <zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h>
13 : #include <zephyr/mgmt/mcumgr/smp/smp_client.h>
14 :
15 : /**
16 : * @brief MCUmgr Image management client API
17 : * @defgroup mcumgr_img_mgmt_client Image Management Client
18 : * @ingroup mcumgr_img_mgmt
19 : * @{
20 : */
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /**
27 : * @brief Image list flags.
28 : */
29 1 : struct mcumgr_image_list_flags {
30 : /** Bootable image */
31 1 : bool bootable: 1;
32 : /** Pending update state */
33 1 : bool pending: 1;
34 : /** Confirmed image */
35 1 : bool confirmed: 1;
36 : /** Active image */
37 1 : bool active: 1;
38 : /** Permanent image state */
39 1 : bool permanent: 1;
40 : };
41 :
42 : /**
43 : * @brief Image list data.
44 : */
45 1 : struct mcumgr_image_data {
46 : /** Image slot num */
47 1 : uint32_t slot_num;
48 : /** Image number */
49 1 : uint32_t img_num;
50 : /** Image SHA256 checksum */
51 1 : char hash[IMG_MGMT_DATA_SHA_LEN];
52 : /** Image Version */
53 1 : char version[IMG_MGMT_VER_MAX_STR_LEN + 1];
54 : /** Image Flags */
55 1 : struct mcumgr_image_list_flags flags;
56 : };
57 :
58 : /**
59 : * @brief MCUmgr Image list response.
60 : */
61 1 : struct mcumgr_image_state {
62 : /** Status */
63 1 : enum mcumgr_err_t status;
64 : /** Length of image_list */
65 1 : int image_list_length;
66 : /** Image list pointer */
67 1 : struct mcumgr_image_data *image_list;
68 : };
69 :
70 : /**
71 : * @brief MCUmgr Image upload response.
72 : */
73 1 : struct mcumgr_image_upload {
74 : /** Status */
75 1 : enum mcumgr_err_t status;
76 : /** Reported image offset */
77 1 : size_t image_upload_offset;
78 : };
79 :
80 : /**
81 : * @brief IMG mgmt client upload structure
82 : *
83 : * Structure is used internally by the client
84 : */
85 1 : struct img_gr_upload {
86 : /** Image 256-bit hash */
87 1 : char sha256[IMG_MGMT_DATA_SHA_LEN];
88 : /** True when Hash is configured, false when not */
89 1 : bool hash_initialized;
90 : /** Image size */
91 1 : size_t image_size;
92 : /** Image upload offset state */
93 1 : size_t offset;
94 : /** Worst case init upload message size */
95 1 : size_t upload_header_size;
96 : /** Image slot num */
97 1 : uint32_t image_num;
98 : };
99 :
100 : /**
101 : * @brief IMG mgmt client object.
102 : */
103 1 : struct img_mgmt_client {
104 : /** SMP client object */
105 1 : struct smp_client_object *smp_client;
106 : /** Image Upload state data for client internal use */
107 1 : struct img_gr_upload upload;
108 : /** Client image list buffer size */
109 1 : int image_list_length;
110 : /** Image list buffer */
111 1 : struct mcumgr_image_data *image_list;
112 : /** Command status */
113 1 : int status;
114 : };
115 :
116 : /**
117 : * @brief Inilialize image group client.
118 : *
119 : * Function initializes image group client for given SMP client using supplied image data.
120 : *
121 : * @param client IMG mgmt client object
122 : * @param smp_client SMP client object
123 : * @param image_list_size Length of image_list buffer.
124 : * @param image_list Image list buffer pointer.
125 : *
126 : */
127 1 : void img_mgmt_client_init(struct img_mgmt_client *client, struct smp_client_object *smp_client,
128 : int image_list_size, struct mcumgr_image_data *image_list);
129 :
130 : /**
131 : * @brief Initialize image upload.
132 : *
133 : * @param client IMG mgmt client object
134 : * @param image_size Size of image in bytes.
135 : * @param image_num Image slot Num.
136 : * @param image_hash Pointer to HASH for image must be SHA256 hash of entire upload
137 : * if present (32 bytes). Use NULL when HASH from image is not available.
138 : *
139 : * @return 0 on success.
140 : * @return @ref mcumgr_err_t code on failure.
141 : */
142 1 : int img_mgmt_client_upload_init(struct img_mgmt_client *client, size_t image_size,
143 : uint32_t image_num, const char *image_hash);
144 :
145 : /**
146 : * @brief Upload part of image.
147 : *
148 : * @param client IMG mgmt client object
149 : * @param data Pointer to data.
150 : * @param length Length of data
151 : * @param res_buf Pointer for command response structure.
152 : *
153 : * @return 0 on success.
154 : * @return @ref mcumgr_err_t code on failure.
155 : */
156 1 : int img_mgmt_client_upload(struct img_mgmt_client *client, const uint8_t *data, size_t length,
157 : struct mcumgr_image_upload *res_buf);
158 :
159 : /**
160 : * @brief Write image state.
161 : *
162 : * @param client IMG mgmt client object
163 : * @param hash Pointer to Hash (Needed for test).
164 : * @param confirm Set false for test and true for confirmation.
165 : * @param res_buf Pointer for command response structure.
166 : *
167 : * @return 0 on success.
168 : * @return @ref mcumgr_err_t code on failure.
169 : */
170 :
171 1 : int img_mgmt_client_state_write(struct img_mgmt_client *client, char *hash, bool confirm,
172 : struct mcumgr_image_state *res_buf);
173 :
174 : /**
175 : * @brief Read image state.
176 : *
177 : * @param client IMG mgmt client object
178 : * @param res_buf Pointer for command response structure.
179 : *
180 : * @return 0 on success.
181 : * @return @ref mcumgr_err_t code on failure.
182 : */
183 1 : int img_mgmt_client_state_read(struct img_mgmt_client *client, struct mcumgr_image_state *res_buf);
184 :
185 : /**
186 : * @brief Erase selected Image Slot
187 : *
188 : * @param client IMG mgmt client object
189 : * @param slot Slot number
190 : *
191 : * @return 0 on success.
192 : * @return @ref mcumgr_err_t code on failure.
193 : */
194 :
195 1 : int img_mgmt_client_erase(struct img_mgmt_client *client, uint32_t slot);
196 :
197 : /**
198 : * @}
199 : */
200 :
201 : #ifdef __cplusplus
202 : }
203 : #endif
204 :
205 : #endif /* H_IMG_MGMT_CLIENT_ */
|
