1 /* 2 * Copyright (c) 2024, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef UPDATE_AGENT_INTERFACE_H 8 #define UPDATE_AGENT_INTERFACE_H 9 10 #include <stdbool.h> 11 #include <stddef.h> 12 #include <stdint.h> 13 14 #include "common/uuid/uuid.h" 15 #include "protocols/service/fwu/status.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #define FWU_OP_TYPE_READ (0) 22 #define FWU_OP_TYPE_WRITE (1) 23 24 #define FWU_FLAG_PARTIAL_UPDATE (0x01) 25 26 struct fwu_discovery_result { 27 int16_t service_status; 28 uint8_t version_major; 29 uint8_t version_minor; 30 uint64_t max_payload_size; 31 uint32_t flags; 32 uint32_t vendor_specific_flags; 33 }; 34 35 struct update_agent_interface { 36 /** 37 * \brief Discovery 38 * 39 * \param[in] context The update_agent context 40 * \param[out] result Discovery result structure 41 * 42 * \return 0 on success 43 */ 44 int (*discover)(void *context, struct fwu_discovery_result *result); 45 46 /** 47 * \brief Begin staging 48 * 49 * \param[in] context The update_agent context 50 * \param[in] vendor_flags Vendor specific staging flags 51 * \param[in] partial_update_count Number of update_guid elements 52 * \param[in] update_guid Images to update 53 * 54 * 55 * \return 0 on successfully transitioning to the STAGING state 56 */ 57 int (*begin_staging)(void *context, uint32_t vendor_flags, uint32_t partial_update_count, 58 const struct uuid_octets *update_guid); 59 60 /** 61 * \brief End staging 62 * 63 * \param[in] context The update_agent context 64 * 65 * \return 0 on successfully transitioning to the TRIAL state 66 */ 67 int (*end_staging)(void *context); 68 69 /** 70 * \brief Cancel staging 71 * 72 * \param[in] context The update_agent context 73 * 74 * \return 0 on successfully transitioning to the REGULAR state 75 */ 76 int (*cancel_staging)(void *context); 77 78 /** 79 * \brief Open a stream for accessing an fwu stream 80 * 81 * Used for reading or writing data for accessing images or other fwu 82 * related objects. 83 * 84 * \param[in] context The update_agent context 85 * \param[in] uuid Identifies the object to access 86 * \param[in] op_type Read/write operation, use FWU_OP_TYPE_* macros 87 * \param[out] handle For subsequent read/write operations 88 * 89 * \return 0 on success 90 */ 91 int (*open)(void *context, const struct uuid_octets *uuid, uint8_t op_type, 92 uint32_t *handle); 93 94 /** 95 * \brief Write to a previously opened stream 96 * 97 * \param[in] context The update_agent context 98 * \param[in] handle The handle returned by open 99 * \param[in] data Pointer to data 100 * \param[in] data_len The data length 101 * 102 * \return 0 on success 103 */ 104 int (*write_stream)(void *context, uint32_t handle, const uint8_t *data, size_t data_len); 105 106 /** 107 * \brief Read from a previously opened stream 108 * 109 * \param[in] context The update_agent context 110 * \param[in] handle The handle returned by open 111 * \param[in] buf Pointer to buffer to copy to 112 * \param[in] buf_size The size of the buffer 113 * \param[out] read_len The length of data read 114 * \param[out] total_len The total length of the object to read 115 * 116 * \return 0 on success 117 */ 118 int (*read_stream)(void *context, uint32_t handle, uint8_t *buf, size_t buf_size, 119 size_t *read_len, size_t *total_len); 120 121 /** 122 * \brief Close a stream and commit any writes to the stream 123 * 124 * \param[in] context The update_agent context 125 * \param[in] handle The handle returned by open 126 * \param[in] accepted Initial accepted state of an image 127 * \param[in] max_atomic_len Hint, maximum time (in ns) that the Update Agent can execute 128 * continuously without yielding back to the Client. A value of 129 * 0 means that the Update Agent can execute for an unbounded 130 * time. 131 * \param[in] progress Units of work already completed by the Update Agent 132 * \param[in] total_work Units of work the Update Agent must perform until fwu_commit 133 * returns successfully 134 * 135 * \return 0 on success 136 */ 137 int (*commit)(void *context, uint32_t handle, bool accepted, uint32_t max_atomic_len, uint32_t *progress, 138 uint32_t *total_work); 139 140 141 /** 142 * \brief Accept an updated image 143 * 144 * \param[in] context The update_agent context 145 * \param[in] image_type_uuid Identifies the image to accept 146 * 147 * \return 0 on success 148 */ 149 int (*accept_image)(void *context, const struct uuid_octets *image_type_uuid); 150 151 /** 152 * \brief Select previous version 153 * 154 * Revert to a previous good version (if possible). 155 * 156 * \param[in] context The update_agent context 157 * 158 * \return 0 on success 159 */ 160 int (*select_previous)(void *context); 161 }; 162 163 /** 164 * \brief Common update agent instance 165 * 166 * Used by the FWU provider make an association with an agent. 167 */ 168 struct update_agent { 169 /** 170 * \brief The update_agent context 171 * 172 * Points to backend specific instance data. 173 */ 174 void *context; 175 176 /** 177 * \brief The update agent interface 178 * 179 * A concrete agent provides an implementation of this interface. 180 */ 181 const struct update_agent_interface *interface; 182 }; 183 184 int update_agent_discover(struct update_agent *update_agent, struct fwu_discovery_result *result); 185 186 int update_agent_begin_staging(struct update_agent *update_agent, uint32_t vendor_flags, 187 uint32_t partial_update_count, 188 const struct uuid_octets *update_guid); 189 190 int update_agent_end_staging(struct update_agent *update_agent); 191 192 int update_agent_cancel_staging(struct update_agent *update_agent); 193 194 int update_agent_open(struct update_agent *update_agent, const struct uuid_octets *uuid, 195 uint8_t op_type, uint32_t *handle); 196 197 int update_agent_write_stream(struct update_agent *update_agent, uint32_t handle, 198 const uint8_t *data, size_t data_len); 199 200 int update_agent_read_stream(struct update_agent *update_agent, uint32_t handle, uint8_t *buf, 201 size_t buf_size, size_t *read_len, size_t *total_len); 202 203 int update_agent_commit(struct update_agent *update_agent, uint32_t handle, bool accepted, 204 uint32_t max_atomic_len, uint32_t *progress, uint32_t *total_work); 205 206 int update_agent_accept_image(struct update_agent *update_agent, 207 const struct uuid_octets *image_type_uuid); 208 209 int update_agent_select_previous(struct update_agent *update_agent); 210 211 #ifdef __cplusplus 212 } 213 #endif 214 215 #endif /* UPDATE_AGENT_INTERFACE_H */ 216