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