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/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 1 : struct mcumgr_image_list_flags { 29 : /** Bootable image */ 30 1 : bool bootable: 1; 31 : /** Pending update state */ 32 1 : bool pending: 1; 33 : /** Confirmed image */ 34 1 : bool confirmed: 1; 35 : /** Active image */ 36 1 : bool active: 1; 37 : /** Permanent image state */ 38 1 : bool permanent: 1; 39 : }; 40 : 41 : /** 42 : * @brief Image list data. 43 : */ 44 1 : struct mcumgr_image_data { 45 : /** Image slot num */ 46 1 : uint32_t slot_num; 47 : /** Image number */ 48 1 : uint32_t img_num; 49 : /** Image SHA256 checksum */ 50 1 : char hash[IMG_MGMT_DATA_SHA_LEN]; 51 : /** Image Version */ 52 1 : char version[IMG_MGMT_VER_MAX_STR_LEN + 1]; 53 : /** Image Flags */ 54 1 : struct mcumgr_image_list_flags flags; 55 : }; 56 : 57 : /** 58 : * @brief MCUmgr Image list response. 59 : */ 60 1 : struct mcumgr_image_state { 61 : /** Status */ 62 1 : enum mcumgr_err_t status; 63 : /** Length of image_list */ 64 1 : int image_list_length; 65 : /** Image list pointer */ 66 1 : struct mcumgr_image_data *image_list; 67 : }; 68 : 69 : /** 70 : * @brief MCUmgr Image upload response. 71 : */ 72 1 : struct mcumgr_image_upload { 73 : /** Status */ 74 1 : enum mcumgr_err_t status; 75 : /** Reported image offset */ 76 1 : 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 1 : struct img_gr_upload { 85 : /** Image 256-bit hash */ 86 1 : char sha256[IMG_MGMT_DATA_SHA_LEN]; 87 : /** True when Hash is configured, false when not */ 88 1 : bool hash_initialized; 89 : /** Image size */ 90 1 : size_t image_size; 91 : /** Image upload offset state */ 92 1 : size_t offset; 93 : /** Worst case init upload message size */ 94 1 : size_t upload_header_size; 95 : /** Image slot num */ 96 1 : uint32_t image_num; 97 : }; 98 : 99 : /** 100 : * @brief IMG mgmt client object. 101 : */ 102 1 : struct img_mgmt_client { 103 : /** SMP client object */ 104 1 : struct smp_client_object *smp_client; 105 : /** Image Upload state data for client internal use */ 106 1 : struct img_gr_upload upload; 107 : /** Client image list buffer size */ 108 1 : int image_list_length; 109 : /** Image list buffer */ 110 1 : struct mcumgr_image_data *image_list; 111 : /** Command status */ 112 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
