1 /* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */
2 #ifndef FW_UPDATE_H
3 #define FW_UPDATE_H
4
5 #ifdef __cplusplus
6 extern "C" {
7 #endif
8
9 #include <libpldm/api.h>
10 #include <libpldm/base.h>
11 #include <libpldm/pldm_types.h>
12 #include <libpldm/utils.h>
13
14 #include <stdbool.h>
15 #include <stddef.h>
16 #include <stdint.h>
17
18 #define PLDM_FWUP_COMPONENT_BITMAP_MULTIPLE 8
19 #define PLDM_FWUP_INVALID_COMPONENT_COMPARISON_TIMESTAMP 0xffffffff
20 #define PLDM_QUERY_DEVICE_IDENTIFIERS_REQ_BYTES 0
21
22 /** @brief Length of QueryDownstreamDevices response defined in DSP0267_1.1.0
23 * Table 15 - QueryDownstreamDevices command format.
24 *
25 * 1 byte for completion code
26 * 1 byte for downstream device update supported
27 * 2 bytes for number of downstream devices
28 * 2 bytes for max number of downstream devices
29 * 4 bytes for capabilities
30 */
31 #define PLDM_QUERY_DOWNSTREAM_DEVICES_RESP_BYTES 10
32
33 /** @brief Length of QueryDownstreamIdentifiers request defined in DSP0267_1.1.0
34 * Table 16 - QueryDownstreamIdentifiers command format.
35 *
36 * 4 bytes for data transfer handle
37 * 1 byte for transfer operation flag
38 */
39 #define PLDM_QUERY_DOWNSTREAM_IDENTIFIERS_REQ_BYTES 5
40
41 /** @brief Minimum length of QueryDownstreamIdentifiers response from DSP0267_1.1.0
42 * if the complement code is success.
43 *
44 * 1 byte for completion code
45 * 4 bytes for next data transfer handle
46 * 1 byte for transfer flag
47 * 4 bytes for downstream devices length
48 * 2 bytes for number of downstream devices
49 */
50 #define PLDM_QUERY_DOWNSTREAM_IDENTIFIERS_RESP_MIN_LEN 12
51
52 /** @brief Minimum length of device descriptor, 2 bytes for descriptor type,
53 * 2 bytes for descriptor length and at least 1 byte of descriptor data
54 */
55 #define PLDM_FWUP_DEVICE_DESCRIPTOR_MIN_LEN 5
56
57 /** @brief Length of GetDownstreamFirmwareParameters request defined in DSP0267_1.1.0
58 *
59 * 4 bytes for Data Transfer Handle
60 * 1 byte for Transfer Operation Flag
61 */
62 #define PLDM_GET_DOWNSTREAM_FIRMWARE_PARAMETERS_REQ_BYTES 5
63
64 /** @brief Minimum length of GetDownstreamFirmwareParameters response from
65 * DSP0267_1.1.0 if the completion code is success.
66 *
67 * 1 byte for completion code
68 * 4 bytes for next data transfer handle
69 * 1 byte for transfer flag
70 * 4 bytes for FDP capabilities during update
71 * 2 bytes for downstream device count
72 */
73 #define PLDM_GET_DOWNSTREAM_FIRMWARE_PARAMETERS_RESP_MIN_LEN 12
74
75 /** @brief Minimum length of DownstreamDeviceParameterTable entry from
76 * DSP0267_1.1.0 table 21 - DownstreamDeviceParameterTable
77 *
78 * 2 bytes for Downstream Device Index
79 * 4 bytes for Active Component Comparison Stamp
80 * 1 byte for Active Component Version String Type
81 * 1 byte for Active Component Version String Length
82 * 8 bytes for Active Component Release Date
83 * 4 bytes for Pending Component Comparison Stamp
84 * 1 byte for Pending Component Version String Type
85 * 1 byte for Pending Component Version String Length
86 * 8 bytes for Pending Component Release Date
87 * 2 bytes for Component Activation Methods
88 * 4 bytes for Capabilities During Update
89 */
90 #define PLDM_DOWNSTREAM_DEVICE_PARAMETERS_ENTRY_MIN_LEN 36
91
92 #define PLDM_GET_FIRMWARE_PARAMETERS_REQ_BYTES 0
93 #define PLDM_FWUP_BASELINE_TRANSFER_SIZE 32
94 #define PLDM_FWUP_MIN_OUTSTANDING_REQ 1
95 #define PLDM_GET_STATUS_REQ_BYTES 0
96 /* Maximum progress percentage value*/
97 #define PLDM_FWUP_MAX_PROGRESS_PERCENT 0x65
98 #define PLDM_CANCEL_UPDATE_COMPONENT_REQ_BYTES 0
99 #define PLDM_CANCEL_UPDATE_REQ_BYTES 0
100
101 /** @brief PLDM component release data size in bytes defined in DSP0267_1.1.0
102 * Table 14 - ComponentParameterTable and Table 21 - ComponentParameterTable
103 *
104 * The size can be used in `ASCII[8] - ActiveComponentReleaseDate` and
105 * `ASCII[8] - PendingComponentReleaseDate` fields in the tables above.
106 */
107 #define PLDM_FWUP_COMPONENT_RELEASE_DATA_LEN 8
108
109 /** @brief PLDM Firmware update commands
110 */
111 enum pldm_firmware_update_commands {
112 PLDM_QUERY_DEVICE_IDENTIFIERS = 0x01,
113 PLDM_GET_FIRMWARE_PARAMETERS = 0x02,
114 PLDM_QUERY_DOWNSTREAM_DEVICES = 0x03,
115 PLDM_QUERY_DOWNSTREAM_IDENTIFIERS = 0x04,
116 PLDM_QUERY_DOWNSTREAM_FIRMWARE_PARAMETERS = 0x05,
117 PLDM_REQUEST_UPDATE = 0x10,
118 PLDM_PASS_COMPONENT_TABLE = 0x13,
119 PLDM_UPDATE_COMPONENT = 0x14,
120 PLDM_REQUEST_FIRMWARE_DATA = 0x15,
121 PLDM_TRANSFER_COMPLETE = 0x16,
122 PLDM_VERIFY_COMPLETE = 0x17,
123 PLDM_APPLY_COMPLETE = 0x18,
124 PLDM_ACTIVATE_FIRMWARE = 0x1a,
125 PLDM_GET_STATUS = 0x1b,
126 PLDM_CANCEL_UPDATE_COMPONENT = 0x1c,
127 PLDM_CANCEL_UPDATE = 0x1d
128 };
129
130 /** @brief PLDM Firmware update completion codes
131 */
132 enum pldm_firmware_update_completion_codes {
133 PLDM_FWUP_NOT_IN_UPDATE_MODE = 0x80,
134 PLDM_FWUP_ALREADY_IN_UPDATE_MODE = 0x81,
135 PLDM_FWUP_DATA_OUT_OF_RANGE = 0x82,
136 PLDM_FWUP_INVALID_TRANSFER_LENGTH = 0x83,
137 PLDM_FWUP_INVALID_STATE_FOR_COMMAND = 0x84,
138 PLDM_FWUP_INCOMPLETE_UPDATE = 0x85,
139 PLDM_FWUP_BUSY_IN_BACKGROUND = 0x86,
140 PLDM_FWUP_CANCEL_PENDING = 0x87,
141 PLDM_FWUP_COMMAND_NOT_EXPECTED = 0x88,
142 PLDM_FWUP_RETRY_REQUEST_FW_DATA = 0x89,
143 PLDM_FWUP_UNABLE_TO_INITIATE_UPDATE = 0x8a,
144 PLDM_FWUP_ACTIVATION_NOT_REQUIRED = 0x8b,
145 PLDM_FWUP_SELF_CONTAINED_ACTIVATION_NOT_PERMITTED = 0x8c,
146 PLDM_FWUP_NO_DEVICE_METADATA = 0x8d,
147 PLDM_FWUP_RETRY_REQUEST_UPDATE = 0x8e,
148 PLDM_FWUP_NO_PACKAGE_DATA = 0x8f,
149 PLDM_FWUP_INVALID_TRANSFER_HANDLE = 0x90,
150 PLDM_FWUP_INVALID_TRANSFER_OPERATION_FLAG = 0x91,
151 PLDM_FWUP_ACTIVATE_PENDING_IMAGE_NOT_PERMITTED = 0x92,
152 PLDM_FWUP_PACKAGE_DATA_ERROR = 0x93
153 };
154
155 /** @brief String type values defined in the PLDM firmware update specification
156 */
157 enum pldm_firmware_update_string_type {
158 PLDM_STR_TYPE_UNKNOWN = 0,
159 PLDM_STR_TYPE_ASCII = 1,
160 PLDM_STR_TYPE_UTF_8 = 2,
161 PLDM_STR_TYPE_UTF_16 = 3,
162 PLDM_STR_TYPE_UTF_16LE = 4,
163 PLDM_STR_TYPE_UTF_16BE = 5
164 };
165
166 /** @brief Descriptor types defined in PLDM firmware update specification
167 */
168 enum pldm_firmware_update_descriptor_types {
169 PLDM_FWUP_PCI_VENDOR_ID = 0x0000,
170 PLDM_FWUP_IANA_ENTERPRISE_ID = 0x0001,
171 PLDM_FWUP_UUID = 0x0002,
172 PLDM_FWUP_PNP_VENDOR_ID = 0x0003,
173 PLDM_FWUP_ACPI_VENDOR_ID = 0x0004,
174 PLDM_FWUP_IEEE_ASSIGNED_COMPANY_ID = 0x0005,
175 PLDM_FWUP_SCSI_VENDOR_ID = 0x0006,
176 PLDM_FWUP_PCI_DEVICE_ID = 0x0100,
177 PLDM_FWUP_PCI_SUBSYSTEM_VENDOR_ID = 0x0101,
178 PLDM_FWUP_PCI_SUBSYSTEM_ID = 0x0102,
179 PLDM_FWUP_PCI_REVISION_ID = 0x0103,
180 PLDM_FWUP_PNP_PRODUCT_IDENTIFIER = 0x0104,
181 PLDM_FWUP_ACPI_PRODUCT_IDENTIFIER = 0x0105,
182 PLDM_FWUP_ASCII_MODEL_NUMBER_LONG_STRING = 0x0106,
183 PLDM_FWUP_ASCII_MODEL_NUMBER_SHORT_STRING = 0x0107,
184 PLDM_FWUP_SCSI_PRODUCT_ID = 0x0108,
185 PLDM_FWUP_UBM_CONTROLLER_DEVICE_CODE = 0x0109,
186 PLDM_FWUP_VENDOR_DEFINED = 0xffff
187 };
188
189 /** @brief Descriptor types length defined in PLDM firmware update specification
190 */
191 enum pldm_firmware_update_descriptor_types_length {
192 PLDM_FWUP_PCI_VENDOR_ID_LENGTH = 2,
193 PLDM_FWUP_IANA_ENTERPRISE_ID_LENGTH = 4,
194 PLDM_FWUP_UUID_LENGTH = 16,
195 PLDM_FWUP_PNP_VENDOR_ID_LENGTH = 3,
196 PLDM_FWUP_ACPI_VENDOR_ID_LENGTH = 4,
197 PLDM_FWUP_IEEE_ASSIGNED_COMPANY_ID_LENGTH = 3,
198 PLDM_FWUP_SCSI_VENDOR_ID_LENGTH = 8,
199 PLDM_FWUP_PCI_DEVICE_ID_LENGTH = 2,
200 PLDM_FWUP_PCI_SUBSYSTEM_VENDOR_ID_LENGTH = 2,
201 PLDM_FWUP_PCI_SUBSYSTEM_ID_LENGTH = 2,
202 PLDM_FWUP_PCI_REVISION_ID_LENGTH = 1,
203 PLDM_FWUP_PNP_PRODUCT_IDENTIFIER_LENGTH = 4,
204 PLDM_FWUP_ACPI_PRODUCT_IDENTIFIER_LENGTH = 4,
205 PLDM_FWUP_ASCII_MODEL_NUMBER_LONG_STRING_LENGTH = 40,
206 PLDM_FWUP_ASCII_MODEL_NUMBER_SHORT_STRING_LENGTH = 10,
207 PLDM_FWUP_SCSI_PRODUCT_ID_LENGTH = 16,
208 PLDM_FWUP_UBM_CONTROLLER_DEVICE_CODE_LENGTH = 4
209 };
210
211 /** @brief ComponentClassification values defined in firmware update
212 * specification
213 */
214 enum pldm_component_classification_values {
215 PLDM_COMP_UNKNOWN = 0x0000,
216 PLDM_COMP_OTHER = 0x0001,
217 PLDM_COMP_DRIVER = 0x0002,
218 PLDM_COMP_CONFIGURATION_SOFTWARE = 0x0003,
219 PLDM_COMP_APPLICATION_SOFTWARE = 0x0004,
220 PLDM_COMP_INSTRUMENTATION = 0x0005,
221 PLDM_COMP_FIRMWARE_OR_BIOS = 0x0006,
222 PLDM_COMP_DIAGNOSTIC_SOFTWARE = 0x0007,
223 PLDM_COMP_OPERATING_SYSTEM = 0x0008,
224 PLDM_COMP_MIDDLEWARE = 0x0009,
225 PLDM_COMP_FIRMWARE = 0x000a,
226 PLDM_COMP_BIOS_OR_FCODE = 0x000b,
227 PLDM_COMP_SUPPORT_OR_SERVICEPACK = 0x000c,
228 PLDM_COMP_SOFTWARE_BUNDLE = 0x000d,
229 PLDM_COMP_DOWNSTREAM_DEVICE = 0xffff
230 };
231
232 /** @brief ComponentActivationMethods is the bit position in the bitfield that
233 * provides the capability of the FD for firmware activation. Multiple
234 * activation methods can be supported.
235 */
236 enum pldm_comp_activation_methods {
237 PLDM_ACTIVATION_AUTOMATIC = 0,
238 PLDM_ACTIVATION_SELF_CONTAINED = 1,
239 PLDM_ACTIVATION_MEDIUM_SPECIFIC_RESET = 2,
240 PLDM_ACTIVATION_SYSTEM_REBOOT = 3,
241 PLDM_ACTIVATION_DC_POWER_CYCLE = 4,
242 PLDM_ACTIVATION_AC_POWER_CYCLE = 5,
243 PLDM_SUPPORTS_ACTIVATE_PENDING_IMAGE = 6,
244 PLDM_SUPPORTS_ACTIVATE_PENDING_IMAGE_SET = 7
245 };
246
247 /** @brief ComponentResponse values in the response of PassComponentTable
248 */
249 enum pldm_component_responses {
250 PLDM_CR_COMP_CAN_BE_UPDATED = 0,
251 PLDM_CR_COMP_MAY_BE_UPDATEABLE = 1
252 };
253
254 /** @brief ComponentResponseCode values in the response of PassComponentTable
255 */
256 enum pldm_component_response_codes {
257 PLDM_CRC_COMP_CAN_BE_UPDATED = 0x00,
258 PLDM_CRC_COMP_COMPARISON_STAMP_IDENTICAL = 0x01,
259 PLDM_CRC_COMP_COMPARISON_STAMP_LOWER = 0x02,
260 PLDM_CRC_INVALID_COMP_COMPARISON_STAMP = 0x03,
261 PLDM_CRC_COMP_CONFLICT = 0x04,
262 PLDM_CRC_COMP_PREREQUISITES_NOT_MET = 0x05,
263 PLDM_CRC_COMP_NOT_SUPPORTED = 0x06,
264 PLDM_CRC_COMP_SECURITY_RESTRICTIONS = 0x07,
265 PLDM_CRC_INCOMPLETE_COMP_IMAGE_SET = 0x08,
266 PLDM_CRC_ACTIVE_IMAGE_NOT_UPDATEABLE_SUBSEQUENTLY = 0x09,
267 PLDM_CRC_COMP_VER_STR_IDENTICAL = 0x0a,
268 PLDM_CRC_COMP_VER_STR_LOWER = 0x0b,
269 PLDM_CRC_VENDOR_COMP_RESP_CODE_RANGE_MIN = 0xd0,
270 PLDM_CRC_VENDOR_COMP_RESP_CODE_RANGE_MAX = 0xef
271 };
272
273 /** @brief ComponentCompatibilityResponse values in the response of
274 * UpdateComponent
275 */
276 enum pldm_component_compatibility_responses {
277 PLDM_CCR_COMP_CAN_BE_UPDATED = 0,
278 PLDM_CCR_COMP_CANNOT_BE_UPDATED = 1
279 };
280
281 /** @brief ComponentCompatibilityResponse Code values in the response of
282 * UpdateComponent
283 */
284 enum pldm_component_compatibility_response_codes {
285 PLDM_CCRC_NO_RESPONSE_CODE = 0x00,
286 PLDM_CCRC_COMP_COMPARISON_STAMP_IDENTICAL = 0x01,
287 PLDM_CCRC_COMP_COMPARISON_STAMP_LOWER = 0x02,
288 PLDM_CCRC_INVALID_COMP_COMPARISON_STAMP = 0x03,
289 PLDM_CCRC_COMP_CONFLICT = 0x04,
290 PLDM_CCRC_COMP_PREREQUISITES_NOT_MET = 0x05,
291 PLDM_CCRC_COMP_NOT_SUPPORTED = 0x06,
292 PLDM_CCRC_COMP_SECURITY_RESTRICTIONS = 0x07,
293 PLDM_CCRC_INCOMPLETE_COMP_IMAGE_SET = 0x08,
294 PLDM_CCRC_COMP_INFO_NO_MATCH = 0x09,
295 PLDM_CCRC_COMP_VER_STR_IDENTICAL = 0x0a,
296 PLDM_CCRC_COMP_VER_STR_LOWER = 0x0b,
297 PLDM_CCRC_VENDOR_COMP_RESP_CODE_RANGE_MIN = 0xd0,
298 PLDM_CCRC_VENDOR_COMP_RESP_CODE_RANGE_MAX = 0xef
299 };
300
301 /** @brief Common error codes in TransferComplete, VerifyComplete and
302 * ApplyComplete request
303 */
304 enum pldm_firmware_update_common_error_codes {
305 PLDM_FWUP_TIME_OUT = 0x09,
306 PLDM_FWUP_GENERIC_ERROR = 0x0a
307 };
308
309 /** @brief TransferResult values in the request of TransferComplete
310 */
311 enum pldm_firmware_update_transfer_result_values {
312 PLDM_FWUP_TRANSFER_SUCCESS = 0x00,
313 PLDM_FWUP_TRANSFER_ERROR_IMAGE_CORRUPT = 0x02,
314 PLDM_FWUP_TRANSFER_ERROR_VERSION_MISMATCH = 0x02,
315 PLDM_FWUP_FD_ABORTED_TRANSFER = 0x03,
316 PLDM_FWUP_FD_ABORTED_TRANSFER_LOW_POWER_STATE = 0x0b,
317 PLDM_FWUP_FD_ABORTED_TRANSFER_RESET_NEEDED = 0x0c,
318 PLDM_FWUP_FD_ABORTED_TRANSFER_STORAGE_ISSUE = 0x0d,
319 PLDM_FWUP_VENDOR_TRANSFER_RESULT_RANGE_MIN = 0x70,
320 PLDM_FWUP_VENDOR_TRANSFER_RESULT_RANGE_MAX = 0x8f
321 };
322
323 /**@brief VerifyResult values in the request of VerifyComplete
324 */
325 enum pldm_firmware_update_verify_result_values {
326 PLDM_FWUP_VERIFY_SUCCESS = 0x00,
327 PLDM_FWUP_VERIFY_ERROR_VERIFICATION_FAILURE = 0x01,
328 PLDM_FWUP_VERIFY_ERROR_VERSION_MISMATCH = 0x02,
329 PLDM_FWUP_VERIFY_FAILED_FD_SECURITY_CHECKS = 0x03,
330 PLDM_FWUP_VERIFY_ERROR_IMAGE_INCOMPLETE = 0x04,
331 PLDM_FWUP_VENDOR_VERIFY_RESULT_RANGE_MIN = 0x90,
332 PLDM_FWUP_VENDOR_VERIFY_RESULT_RANGE_MAX = 0xaf
333 };
334
335 /**@brief ApplyResult values in the request of ApplyComplete
336 */
337 enum pldm_firmware_update_apply_result_values {
338 PLDM_FWUP_APPLY_SUCCESS = 0x00,
339 PLDM_FWUP_APPLY_SUCCESS_WITH_ACTIVATION_METHOD = 0x01,
340 PLDM_FWUP_APPLY_FAILURE_MEMORY_ISSUE = 0x02,
341 PLDM_FWUP_VENDOR_APPLY_RESULT_RANGE_MIN = 0xb0,
342 PLDM_FWUP_VENDOR_APPLY_RESULT_RANGE_MAX = 0xcf
343 };
344
345 /** @brief SelfContainedActivationRequest in the request of ActivateFirmware
346 */
347 enum pldm_self_contained_activation_req {
348 PLDM_NOT_ACTIVATE_SELF_CONTAINED_COMPONENTS = false,
349 PLDM_ACTIVATE_SELF_CONTAINED_COMPONENTS = true
350 };
351
352 /** @brief Current state/previous state of the FD or FDP returned in GetStatus
353 * response
354 */
355 enum pldm_firmware_device_states {
356 PLDM_FD_STATE_IDLE = 0,
357 PLDM_FD_STATE_LEARN_COMPONENTS = 1,
358 PLDM_FD_STATE_READY_XFER = 2,
359 PLDM_FD_STATE_DOWNLOAD = 3,
360 PLDM_FD_STATE_VERIFY = 4,
361 PLDM_FD_STATE_APPLY = 5,
362 PLDM_FD_STATE_ACTIVATE = 6
363 };
364
365 /** @brief Firmware device aux state in GetStatus response
366 */
367 enum pldm_get_status_aux_states {
368 PLDM_FD_OPERATION_IN_PROGRESS = 0,
369 PLDM_FD_OPERATION_SUCCESSFUL = 1,
370 PLDM_FD_OPERATION_FAILED = 2,
371 PLDM_FD_IDLE_LEARN_COMPONENTS_READ_XFER = 3
372 };
373
374 /** @brief Firmware device aux state status in GetStatus response
375 */
376 enum pldm_get_status_aux_state_status_values {
377 PLDM_FD_AUX_STATE_IN_PROGRESS_OR_SUCCESS = 0x00,
378 PLDM_FD_TIMEOUT = 0x09,
379 PLDM_FD_GENERIC_ERROR = 0x0a,
380 PLDM_FD_VENDOR_DEFINED_STATUS_CODE_START = 0x70,
381 PLDM_FD_VENDOR_DEFINED_STATUS_CODE_END = 0xef
382 };
383
384 /** @brief Firmware device reason code in GetStatus response
385 */
386 enum pldm_get_status_reason_code_values {
387 PLDM_FD_INITIALIZATION = 0,
388 PLDM_FD_ACTIVATE_FW = 1,
389 PLDM_FD_CANCEL_UPDATE = 2,
390 PLDM_FD_TIMEOUT_LEARN_COMPONENT = 3,
391 PLDM_FD_TIMEOUT_READY_XFER = 4,
392 PLDM_FD_TIMEOUT_DOWNLOAD = 5,
393 PLDM_FD_TIMEOUT_VERIFY = 6,
394 PLDM_FD_TIMEOUT_APPLY = 7,
395 PLDM_FD_STATUS_VENDOR_DEFINED_MIN = 200,
396 PLDM_FD_STATUS_VENDOR_DEFINED_MAX = 255
397 };
398
399 /** @brief Components functional indicator in CancelUpdate response
400 */
401 enum pldm_firmware_update_non_functioning_component_indication {
402 PLDM_FWUP_COMPONENTS_FUNCTIONING = 0,
403 PLDM_FWUP_COMPONENTS_NOT_FUNCTIONING = 1
404 };
405
406 /** @brief Downstream device update supported in QueryDownstreamDevices response
407 * defined in DSP0267_1.1.0
408 */
409 enum pldm_firmware_update_downstream_device_update_supported {
410 PLDM_FWUP_DOWNSTREAM_DEVICE_UPDATE_NOT_SUPPORTED = 0,
411 PLDM_FWUP_DOWNSTREAM_DEVICE_UPDATE_SUPPORTED = 1
412 };
413
414 /* An arbitrary limit, for static storage */
415 #define PLDM_FIRMWARE_MAX_STRING 64
416
417 /** @struct pldm_firmware_string
418 *
419 * A fixed maximum length PLDM firmware string
420 */
421 struct pldm_firmware_string {
422 enum pldm_firmware_update_string_type str_type;
423 uint8_t str_len;
424 uint8_t str_data[PLDM_FIRMWARE_MAX_STRING];
425 };
426
427 /** @struct pldm_firmware_version
428 *
429 * A PLDM component version
430 */
431 struct pldm_firmware_version {
432 uint32_t comparison_stamp;
433 struct pldm_firmware_string str;
434 uint8_t date[PLDM_FWUP_COMPONENT_RELEASE_DATA_LEN];
435 };
436
437 /** @struct pldm_package_header_information
438 *
439 * Structure representing fixed part of package header information
440 */
441 struct pldm_package_header_information {
442 uint8_t uuid[PLDM_FWUP_UUID_LENGTH];
443 uint8_t package_header_format_version;
444 uint16_t package_header_size;
445 uint8_t package_release_date_time[PLDM_TIMESTAMP104_SIZE];
446 uint16_t component_bitmap_bit_length;
447 uint8_t package_version_string_type;
448 uint8_t package_version_string_length;
449 } __attribute__((packed));
450
451 /** @struct pldm_firmware_device_id_record
452 *
453 * Structure representing firmware device ID record
454 */
455 struct pldm_firmware_device_id_record {
456 uint16_t record_length;
457 uint8_t descriptor_count;
458 bitfield32_t device_update_option_flags;
459 uint8_t comp_image_set_version_string_type;
460 uint8_t comp_image_set_version_string_length;
461 uint16_t fw_device_pkg_data_length;
462 } __attribute__((packed));
463
464 /** @struct pldm_descriptor_tlv
465 *
466 * Structure representing descriptor type, length and value
467 */
468 struct pldm_descriptor_tlv {
469 uint16_t descriptor_type;
470 uint16_t descriptor_length;
471 uint8_t descriptor_data[1];
472 } __attribute__((packed));
473
474 /** @struct pldm_vendor_defined_descriptor_title_data
475 *
476 * Structure representing vendor defined descriptor title sections
477 */
478 struct pldm_vendor_defined_descriptor_title_data {
479 uint8_t vendor_defined_descriptor_title_str_type;
480 uint8_t vendor_defined_descriptor_title_str_len;
481 uint8_t vendor_defined_descriptor_title_str[1];
482 } __attribute__((packed));
483
484 /** @struct pldm_component_image_information
485 *
486 * Structure representing fixed part of individual component information in
487 * PLDM firmware update package
488 */
489 struct pldm_component_image_information {
490 uint16_t comp_classification;
491 uint16_t comp_identifier;
492 uint32_t comp_comparison_stamp;
493 bitfield16_t comp_options;
494 bitfield16_t requested_comp_activation_method;
495 uint32_t comp_location_offset;
496 uint32_t comp_size;
497 uint8_t comp_version_string_type;
498 uint8_t comp_version_string_length;
499 } __attribute__((packed));
500
501 /** @struct pldm_query_device_identifiers_resp
502 *
503 * Structure representing query device identifiers response.
504 */
505 struct pldm_query_device_identifiers_resp {
506 uint8_t completion_code;
507 uint32_t device_identifiers_len;
508 uint8_t descriptor_count;
509 } __attribute__((packed));
510
511 /** @struct pldm_get_firmware_parameters_resp
512 *
513 * Structure representing the fixed part of GetFirmwareParameters response
514 */
515 struct pldm_get_firmware_parameters_resp {
516 uint8_t completion_code;
517 bitfield32_t capabilities_during_update;
518 uint16_t comp_count;
519 uint8_t active_comp_image_set_ver_str_type;
520 uint8_t active_comp_image_set_ver_str_len;
521 uint8_t pending_comp_image_set_ver_str_type;
522 uint8_t pending_comp_image_set_ver_str_len;
523 } __attribute__((packed));
524
525 /** @struct pldm_get_firmware_parameters_resp_full
526 *
527 * Structure representing a full GetFirmwareParameters response
528 */
529 struct pldm_get_firmware_parameters_resp_full {
530 uint8_t completion_code;
531 bitfield32_t capabilities_during_update;
532 uint16_t comp_count;
533 struct pldm_firmware_string active_comp_image_set_ver_str;
534 struct pldm_firmware_string pending_comp_image_set_ver_str;
535 };
536
537 /** @struct pldm_query_downstream_devices_resp
538 *
539 * Structure representing response of QueryDownstreamDevices.
540 * The definition can be found Table 15 - QueryDownstreamDevices command format
541 * in DSP0267_1.1.0
542 */
543 struct pldm_query_downstream_devices_resp {
544 uint8_t completion_code;
545 uint8_t downstream_device_update_supported;
546 uint16_t number_of_downstream_devices;
547 uint16_t max_number_of_downstream_devices;
548 bitfield32_t capabilities;
549 };
550
551 /** @struct pldm_component_parameter_entry
552 *
553 * Structure representing component parameter table entry, as wire format.
554 */
555 struct pldm_component_parameter_entry {
556 uint16_t comp_classification;
557 uint16_t comp_identifier;
558 uint8_t comp_classification_index;
559 uint32_t active_comp_comparison_stamp;
560 uint8_t active_comp_ver_str_type;
561 uint8_t active_comp_ver_str_len;
562 uint8_t active_comp_release_date[8];
563 uint32_t pending_comp_comparison_stamp;
564 uint8_t pending_comp_ver_str_type;
565 uint8_t pending_comp_ver_str_len;
566 uint8_t pending_comp_release_date[8];
567 bitfield16_t comp_activation_methods;
568 bitfield32_t capabilities_during_update;
569 } __attribute__((packed));
570
571 /** @struct pldm_component_parameter_entry_full
572 *
573 * Structure representing component parameter table entry.
574 * This is non-packed (contrast with struct pldm_component_parameter_entry),
575 * with version strings included.
576 */
577 struct pldm_component_parameter_entry_full {
578 uint16_t comp_classification;
579 uint16_t comp_identifier;
580 uint8_t comp_classification_index;
581
582 struct pldm_firmware_version active_ver;
583 struct pldm_firmware_version pending_ver;
584
585 bitfield16_t comp_activation_methods;
586 bitfield32_t capabilities_during_update;
587 };
588
589 /** @struct pldm_query_downstream_identifiers_req
590 *
591 * Structure for QueryDownstreamIdentifiers request defined in Table 16 -
592 * QueryDownstreamIdentifiers command format in DSP0267_1.1.0
593 */
594 struct pldm_query_downstream_identifiers_req {
595 uint32_t data_transfer_handle;
596 uint8_t transfer_operation_flag;
597 };
598
599 /** @struct pldm_query_downstream_identifiers_resp
600 *
601 * Structure representing the fixed part of QueryDownstreamIdentifiers response
602 * defined in Table 16 - QueryDownstreamIdentifiers command format, and
603 * Table 17 - QueryDownstreamIdentifiers response definition in DSP0267_1.1.0.
604 *
605 * Squash the two tables into one since the definition of
606 * Table 17 is `Portion of QueryDownstreamIdentifiers response`
607 */
608 struct pldm_query_downstream_identifiers_resp {
609 uint8_t completion_code;
610 uint32_t next_data_transfer_handle;
611 uint8_t transfer_flag;
612 uint32_t downstream_devices_length;
613 uint16_t number_of_downstream_devices;
614 };
615
616 /** @struct pldm_downstream_device
617 *
618 * Structure representing downstream device information defined in
619 * Table 18 - DownstreamDevice definition in DSP0267_1.1.0
620 */
621 struct pldm_downstream_device {
622 uint16_t downstream_device_index;
623 uint8_t downstream_descriptor_count;
624 };
625 #define PLDM_DOWNSTREAM_DEVICE_BYTES 3
626
627 struct pldm_downstream_device_iter {
628 struct variable_field field;
629 size_t devs;
630 };
631
632 LIBPLDM_ITERATOR
pldm_downstream_device_iter_end(const struct pldm_downstream_device_iter * iter)633 bool pldm_downstream_device_iter_end(
634 const struct pldm_downstream_device_iter *iter)
635 {
636 return !iter->devs;
637 }
638
639 LIBPLDM_ITERATOR
pldm_downstream_device_iter_next(struct pldm_downstream_device_iter * iter)640 bool pldm_downstream_device_iter_next(struct pldm_downstream_device_iter *iter)
641 {
642 if (!iter->devs) {
643 return false;
644 }
645
646 iter->devs--;
647 return true;
648 }
649
650 int decode_pldm_downstream_device_from_iter(
651 struct pldm_downstream_device_iter *iter,
652 struct pldm_downstream_device *dev);
653
654 /** @brief Iterate downstream devices in QueryDownstreamIdentifiers response
655 *
656 * @param devs The @ref "struct pldm_downstream_device_iter" lvalue used as the
657 * out-value from the corresponding call to @ref
658 * decode_query_downstream_identifiers_resp
659 * @param dev The @ref "struct pldm_downstream_device" lvalue into which the
660 * next device instance should be decoded.
661 * @param rc An lvalue of type int into which the return code from the decoding
662 * will be placed.
663 *
664 * Example use of the macro is as follows:
665 *
666 * @code
667 * struct pldm_query_downstream_identifiers_resp resp;
668 * struct pldm_downstream_device_iter devs;
669 * struct pldm_downstream_device dev;
670 * int rc;
671 *
672 * rc = decode_query_downstream_identifiers_resp(..., &resp, &devs);
673 * if (rc) {
674 * // Handle any error from decoding fixed-portion of response
675 * }
676 *
677 * foreach_pldm_downstream_device(devs, dev, rc) {
678 * // Do something with each decoded device placed in `dev`
679 * }
680 *
681 * if (rc) {
682 * // Handle any decoding error while iterating variable-length set of
683 * // devices
684 * }
685 * @endcode
686 */
687 #define foreach_pldm_downstream_device(devs, dev, rc) \
688 for ((rc) = 0; (!pldm_downstream_device_iter_end(&(devs)) && \
689 !((rc) = decode_pldm_downstream_device_from_iter( \
690 &(devs), &(dev)))); \
691 pldm_downstream_device_iter_next(&(devs)))
692
693 /** @struct pldm_descriptor
694 *
695 * Structure representing a type-length-value descriptor as defined in Table 7 -
696 * Descriptor Definition.
697 *
698 * Member values are always host-endian. When decoding messages, the
699 * descriptor_data member points into the message buffer.
700 */
701 struct pldm_descriptor {
702 uint16_t descriptor_type;
703 uint16_t descriptor_length;
704 const void *descriptor_data;
705 };
706
707 struct pldm_descriptor_iter {
708 struct variable_field *field;
709 size_t count;
710 };
711
712 LIBPLDM_ITERATOR
pldm_downstream_device_descriptor_iter_init(struct pldm_downstream_device_iter * devs,const struct pldm_downstream_device * dev)713 struct pldm_descriptor_iter pldm_downstream_device_descriptor_iter_init(
714 struct pldm_downstream_device_iter *devs,
715 const struct pldm_downstream_device *dev)
716 {
717 struct pldm_descriptor_iter iter = { &devs->field,
718 dev->downstream_descriptor_count };
719 return iter;
720 }
721
722 LIBPLDM_ITERATOR
pldm_descriptor_iter_end(const struct pldm_descriptor_iter * iter)723 bool pldm_descriptor_iter_end(const struct pldm_descriptor_iter *iter)
724 {
725 return !iter->count;
726 }
727
728 LIBPLDM_ITERATOR
pldm_descriptor_iter_next(struct pldm_descriptor_iter * iter)729 bool pldm_descriptor_iter_next(struct pldm_descriptor_iter *iter)
730 {
731 if (!iter->count) {
732 return false;
733 }
734
735 iter->count--;
736 return true;
737 }
738
739 int decode_pldm_descriptor_from_iter(struct pldm_descriptor_iter *iter,
740 struct pldm_descriptor *desc);
741
742 /** @brief Iterate a downstream device's descriptors in a
743 * QueryDownstreamIdentifiers response
744 *
745 * @param devs The @ref "struct pldm_downstream_device_iter" lvalue used as the
746 * out-value from the corresponding call to @ref
747 * decode_query_downstream_identifiers_resp
748 * @param dev The @ref "struct pldm_downstream_device" lvalue over whose
749 * descriptors to iterate
750 * @param desc The @ref "struct pldm_descriptor" lvalue into which the next
751 * descriptor instance should be decoded
752 * @param rc An lvalue of type int into which the return code from the decoding
753 * will be placed
754 *
755 * Example use of the macro is as follows:
756 *
757 * @code
758 * struct pldm_query_downstream_identifiers_resp resp;
759 * struct pldm_downstream_device_iter devs;
760 * struct pldm_downstream_device dev;
761 * int rc;
762 *
763 * rc = decode_query_downstream_identifiers_resp(..., &resp, &devs);
764 * if (rc) {
765 * // Handle any error from decoding fixed-portion of response
766 * }
767 *
768 * foreach_pldm_downstream_device(devs, dev, rc) {
769 * struct pldm_descriptor desc;
770 *
771 * foreach_pldm_downstream_device_descriptor(devs, dev, desc, rc) {
772 * // Do something with each decoded descriptor placed in `desc`
773 * }
774 *
775 * if (rc) {
776 * // Handle any decoding error while iterating on the variable-length
777 * // set of descriptors
778 * }
779 * }
780 *
781 * if (rc) {
782 * // Handle any decoding error while iterating variable-length set of
783 * // devices
784 * }
785 * @endcode
786 */
787 #define foreach_pldm_downstream_device_descriptor(devs, dev, desc, rc) \
788 for (struct pldm_descriptor_iter desc##_iter = \
789 ((rc) = 0, pldm_downstream_device_descriptor_iter_init( \
790 &(devs), &(dev))); \
791 (!pldm_descriptor_iter_end(&(desc##_iter)) && \
792 !((rc) = decode_pldm_descriptor_from_iter(&(desc##_iter), \
793 &(desc)))); \
794 pldm_descriptor_iter_next(&(desc##_iter)))
795
796 /** @struct pldm_query_downstream_firmware_param_req
797 *
798 * Structure representing QueryDownstreamFirmwareParameters request
799 */
800 struct pldm_get_downstream_firmware_parameters_req {
801 uint32_t data_transfer_handle;
802 uint8_t transfer_operation_flag;
803 };
804
805 /** @struct pldm_get_downstream_firmware_parameters_resp
806 *
807 * Structure representing the fixed part of QueryDownstreamFirmwareParameters
808 * response in Table 19 - GetDownstreamFirmwareParameters command format, and
809 * Table 20 - QueryDownstreamFirmwareParameters response definition in
810 * DSP0267_1.1.0.
811 *
812 * Squash the two tables into one since the definition of Table 20 is `Portion
813 * of GetDownstreamFirmwareParameters response`
814 */
815 struct pldm_get_downstream_firmware_parameters_resp {
816 uint8_t completion_code;
817 uint32_t next_data_transfer_handle;
818 uint8_t transfer_flag;
819 bitfield32_t fdp_capabilities_during_update;
820 uint16_t downstream_device_count;
821 };
822
823 /** @struct pldm_downstream_device_parameters_entry
824 *
825 * Structure representing downstream device parameter table entry defined in
826 * Table 21 - DownstreamDeviceParameterTable in DSP0267_1.1.0
827 *
828 * Clients should not allocate memory for this struct to decode the response,
829 * use `pldm_downstream_device_parameter_entry_versions` instead to make sure
830 * that the active and pending component version strings are copied from the
831 * message buffer.
832 */
833 struct pldm_downstream_device_parameters_entry {
834 uint16_t downstream_device_index;
835 uint32_t active_comp_comparison_stamp;
836 uint8_t active_comp_ver_str_type;
837 uint8_t active_comp_ver_str_len;
838 /* Append 1 bytes for null termination so that it can be used as a
839 * Null-terminated string.
840 */
841 char active_comp_release_date[PLDM_FWUP_COMPONENT_RELEASE_DATA_LEN + 1];
842 uint32_t pending_comp_comparison_stamp;
843 uint8_t pending_comp_ver_str_type;
844 uint8_t pending_comp_ver_str_len;
845 /* Append 1 bytes for null termination so that it can be used as a
846 * Null-terminated string.
847 */
848 char pending_comp_release_date[PLDM_FWUP_COMPONENT_RELEASE_DATA_LEN + 1];
849 bitfield16_t comp_activation_methods;
850 bitfield32_t capabilities_during_update;
851 const void *active_comp_ver_str;
852 const void *pending_comp_ver_str;
853 };
854
855 /** @struct pldm_request_update_req
856 *
857 * Structure representing fixed part of Request Update request, as wire format.
858 */
859 struct pldm_request_update_req {
860 uint32_t max_transfer_size;
861 uint16_t num_of_comp;
862 uint8_t max_outstanding_transfer_req;
863 uint16_t pkg_data_len;
864 uint8_t comp_image_set_ver_str_type;
865 uint8_t comp_image_set_ver_str_len;
866 } __attribute__((packed));
867
868 /** @struct pldm_request_update_req_full
869 *
870 * Structure representing fixed part of Request Update request, including
871 * version string. This is unpacked (contrast to struct pldm_request_update_req).
872 */
873 struct pldm_request_update_req_full {
874 uint32_t max_transfer_size;
875 uint16_t num_of_comp;
876 uint8_t max_outstanding_transfer_req;
877 uint16_t pkg_data_len;
878
879 struct pldm_firmware_string image_set_ver;
880 };
881
882 /** @struct pldm_request_update_resp
883 *
884 * Structure representing Request Update response
885 */
886 struct pldm_request_update_resp {
887 uint8_t completion_code;
888 uint16_t fd_meta_data_len;
889 uint8_t fd_will_send_pkg_data;
890 } __attribute__((packed));
891
892 /** @struct pldm_pass_component_table_req
893 *
894 * Structure representing PassComponentTable request, wire format.
895 * Version string data is not included.
896 * Prefer pldm_pass_component_table_req_full for new uses.
897 */
898 struct pldm_pass_component_table_req {
899 uint8_t transfer_flag;
900 uint16_t comp_classification;
901 uint16_t comp_identifier;
902 uint8_t comp_classification_index;
903 uint32_t comp_comparison_stamp;
904 uint8_t comp_ver_str_type;
905 uint8_t comp_ver_str_len;
906 } __attribute__((packed));
907
908 /** @struct pldm_pass_component_table_req_full
909 *
910 * Structure representing PassComponentTable request, including
911 * version string storage.
912 */
913 struct pldm_pass_component_table_req_full {
914 uint8_t transfer_flag;
915 uint16_t comp_classification;
916 uint16_t comp_identifier;
917 uint8_t comp_classification_index;
918 uint32_t comp_comparison_stamp;
919 struct pldm_firmware_string version;
920 };
921
922 /** @struct pldm_pass_component_table_resp
923 *
924 * Structure representing PassComponentTable response
925 */
926 struct pldm_pass_component_table_resp {
927 uint8_t completion_code;
928 uint8_t comp_resp;
929 uint8_t comp_resp_code;
930 } __attribute__((packed));
931
932 /** @struct pldm_update_component_req
933 *
934 * Structure representing UpdateComponent request, wire format.
935 * Version string data is not included.
936 * Prefer pldm_update_component_req_full for new uses.
937 */
938 struct pldm_update_component_req {
939 uint16_t comp_classification;
940 uint16_t comp_identifier;
941 uint8_t comp_classification_index;
942 uint32_t comp_comparison_stamp;
943 uint32_t comp_image_size;
944 bitfield32_t update_option_flags;
945 uint8_t comp_ver_str_type;
946 uint8_t comp_ver_str_len;
947 } __attribute__((packed));
948
949 /** @struct pldm_update_component_req_full
950 *
951 * Structure representing UpdateComponent request, including
952 * version string storage.
953 */
954 struct pldm_update_component_req_full {
955 uint16_t comp_classification;
956 uint16_t comp_identifier;
957 uint8_t comp_classification_index;
958
959 uint32_t comp_comparison_stamp;
960 struct pldm_firmware_string version;
961
962 uint32_t comp_image_size;
963 bitfield32_t update_option_flags;
964 };
965
966 /** @struct pldm_update_component_resp
967 *
968 * Structure representing UpdateComponent response
969 */
970 struct pldm_update_component_resp {
971 uint8_t completion_code;
972 uint8_t comp_compatibility_resp;
973 uint8_t comp_compatibility_resp_code;
974 bitfield32_t update_option_flags_enabled;
975 uint16_t time_before_req_fw_data;
976 } __attribute__((packed));
977
978 /** @struct pldm_request_firmware_data_req
979 *
980 * Structure representing RequestFirmwareData request.
981 */
982 struct pldm_request_firmware_data_req {
983 uint32_t offset;
984 uint32_t length;
985 } __attribute__((packed));
986
987 /** @struct pldm_apply_complete_req
988 *
989 * Structure representing ApplyComplete request.
990 */
991 struct pldm_apply_complete_req {
992 uint8_t apply_result;
993 bitfield16_t comp_activation_methods_modification;
994 } __attribute__((packed));
995
996 /** @struct pldm_activate_firmware_req
997 *
998 * Structure representing ActivateFirmware request
999 */
1000 struct pldm_activate_firmware_req {
1001 bool8_t self_contained_activation_req;
1002 } __attribute__((packed));
1003
1004 /** @struct activate_firmware_resp
1005 *
1006 * Structure representing Activate Firmware response
1007 */
1008 struct pldm_activate_firmware_resp {
1009 uint8_t completion_code;
1010 uint16_t estimated_time_activation;
1011 } __attribute__((packed));
1012
1013 /** @struct pldm_get_status_resp
1014 *
1015 * Structure representing GetStatus response.
1016 */
1017 struct pldm_get_status_resp {
1018 uint8_t completion_code;
1019 uint8_t current_state;
1020 uint8_t previous_state;
1021 uint8_t aux_state;
1022 uint8_t aux_state_status;
1023 uint8_t progress_percent;
1024 uint8_t reason_code;
1025 bitfield32_t update_option_flags_enabled;
1026 } __attribute__((packed));
1027
1028 /** @struct pldm_cancel_update_resp
1029 *
1030 * Structure representing CancelUpdate response.
1031 */
1032 struct pldm_cancel_update_resp {
1033 uint8_t completion_code;
1034 bool8_t non_functioning_component_indication;
1035 uint64_t non_functioning_component_bitmap;
1036 } __attribute__((packed));
1037
1038 /** @brief Decode the PLDM package header information
1039 *
1040 * @param[in] data - pointer to package header information
1041 * @param[in] length - available length in the firmware update package
1042 * @param[out] package_header_info - pointer to fixed part of PLDM package
1043 * header information
1044 * @param[out] package_version_str - pointer to package version string
1045 *
1046 * @return pldm_completion_codes
1047 */
1048 int decode_pldm_package_header_info(
1049 const uint8_t *data, size_t length,
1050 struct pldm_package_header_information *package_header_info,
1051 struct variable_field *package_version_str);
1052
1053 /** @brief Decode individual firmware device ID record
1054 *
1055 * @param[in] data - pointer to firmware device ID record
1056 * @param[in] length - available length in the firmware update package
1057 * @param[in] component_bitmap_bit_length - ComponentBitmapBitLengthfield
1058 * parsed from the package header info
1059 * @param[out] fw_device_id_record - pointer to fixed part of firmware device
1060 * id record
1061 * @param[out] applicable_components - pointer to ApplicableComponents
1062 * @param[out] comp_image_set_version_str - pointer to
1063 * ComponentImageSetVersionString
1064 * @param[out] record_descriptors - pointer to RecordDescriptors
1065 * @param[out] fw_device_pkg_data - pointer to FirmwareDevicePackageData
1066 *
1067 * @return pldm_completion_codes
1068 */
1069 int decode_firmware_device_id_record(
1070 const uint8_t *data, size_t length,
1071 uint16_t component_bitmap_bit_length,
1072 struct pldm_firmware_device_id_record *fw_device_id_record,
1073 struct variable_field *applicable_components,
1074 struct variable_field *comp_image_set_version_str,
1075 struct variable_field *record_descriptors,
1076 struct variable_field *fw_device_pkg_data);
1077
1078 /** @brief Decode the record descriptor entries in the firmware update package
1079 * and the Descriptors in the QueryDeviceIDentifiers command
1080 *
1081 * @param[in] data - pointer to descriptor entry
1082 * @param[in] length - remaining length of the descriptor data
1083 * @param[out] descriptor_type - pointer to descriptor type
1084 * @param[out] descriptor_data - pointer to descriptor data
1085 *
1086 * @return pldm_completion_codes
1087 */
1088 int decode_descriptor_type_length_value(const uint8_t *data, size_t length,
1089 uint16_t *descriptor_type,
1090 struct variable_field *descriptor_data);
1091
1092 /** @brief Decode the vendor defined descriptor value
1093 *
1094 * @param[in] data - pointer to vendor defined descriptor value
1095 * @param[in] length - length of the vendor defined descriptor value
1096 * @param[out] descriptor_title_str_type - pointer to vendor defined descriptor
1097 * title string type
1098 * @param[out] descriptor_title_str - pointer to vendor defined descriptor
1099 * title string
1100 * @param[out] descriptor_data - pointer to vendor defined descriptor data
1101 *
1102 * @return pldm_completion_codes
1103 */
1104 int decode_vendor_defined_descriptor_value(
1105 const uint8_t *data, size_t length, uint8_t *descriptor_title_str_type,
1106 struct variable_field *descriptor_title_str,
1107 struct variable_field *descriptor_data);
1108
1109 /** @brief Decode individual component image information
1110 *
1111 * @param[in] data - pointer to component image information
1112 * @param[in] length - available length in the firmware update package
1113 * @param[out] pldm_comp_image_info - pointer to fixed part of component image
1114 * information
1115 * @param[out] comp_version_str - pointer to component version string
1116 *
1117 * @return pldm_completion_codes
1118 */
1119 int decode_pldm_comp_image_info(
1120 const uint8_t *data, size_t length,
1121 struct pldm_component_image_information *pldm_comp_image_info,
1122 struct variable_field *comp_version_str);
1123
1124 /** @brief Create a PLDM request message for QueryDeviceIdentifiers
1125 *
1126 * @param[in] instance_id - Message's instance id
1127 * @param[in] payload_length - Length of the request message payload
1128 * @param[in,out] msg - Message will be written to this
1129 *
1130 * @return pldm_completion_codes
1131 *
1132 * @note Caller is responsible for memory alloc and dealloc of param
1133 * 'msg.payload'
1134 */
1135 int encode_query_device_identifiers_req(uint8_t instance_id,
1136 size_t payload_length,
1137 struct pldm_msg *msg);
1138
1139 /** @brief Create a PLDM response message for QueryDeviceIdentifiers
1140 *
1141 * @param[in] instance_id - Message's instance id
1142 * @param[in] descriptor_count - Number of descriptors
1143 * @param[in] descriptor - Array of descriptors
1144 * @param[in,out] msg - Message will be written to this
1145 * @param[in,out] payload_length - Size of the response message payload, updated
1146 * with used length.
1147 *
1148 * @return 0 on success, a negative errno value on failure.
1149 *
1150 * @note Caller is responsible for memory alloc and dealloc of param
1151 * 'msg.payload'
1152 */
1153 int encode_query_device_identifiers_resp(
1154 uint8_t instance_id, uint8_t descriptor_count,
1155 const struct pldm_descriptor *descriptors, struct pldm_msg *msg,
1156 size_t *payload_length);
1157
1158 /** @brief Decode QueryDeviceIdentifiers response message
1159 *
1160 * @param[in] msg - Response message
1161 * @param[in] payload_length - Length of response message payload
1162 * @param[out] completion_code - Pointer to response msg's PLDM completion code
1163 * @param[out] device_identifiers_len - Pointer to device identifiers length
1164 * @param[out] descriptor_count - Pointer to descriptor count
1165 * @param[out] descriptor_data - Pointer to descriptor data
1166 *
1167 * @return pldm_completion_codes
1168 */
1169 int decode_query_device_identifiers_resp(const struct pldm_msg *msg,
1170 size_t payload_length,
1171 uint8_t *completion_code,
1172 uint32_t *device_identifiers_len,
1173 uint8_t *descriptor_count,
1174 uint8_t **descriptor_data);
1175
1176 /** @brief Create a PLDM request message for GetFirmwareParameters
1177 *
1178 * @param[in] instance_id - Message's instance id
1179 * @param[in] payload_length - Length of the request message payload
1180 * @param[in,out] msg - Message will be written to this
1181 *
1182 * @return pldm_completion_codes
1183 *
1184 * @note Caller is responsible for memory alloc and dealloc of param
1185 * 'msg.payload'
1186 */
1187 int encode_get_firmware_parameters_req(uint8_t instance_id,
1188 size_t payload_length,
1189 struct pldm_msg *msg);
1190
1191 /** @brief Decode GetFirmwareParameters response
1192 *
1193 * @param[in] msg - Response message
1194 * @param[in] payload_length - Length of response message payload
1195 * @param[out] resp_data - Pointer to get firmware parameters response
1196 * @param[out] active_comp_image_set_ver_str - Pointer to active component
1197 * image set version string
1198 * @param[out] pending_comp_image_set_ver_str - Pointer to pending component
1199 * image set version string
1200 * @param[out] comp_parameter_table - Pointer to component parameter table
1201 *
1202 * @return pldm_completion_codes
1203 */
1204 int decode_get_firmware_parameters_resp(
1205 const struct pldm_msg *msg, size_t payload_length,
1206 struct pldm_get_firmware_parameters_resp *resp_data,
1207 struct variable_field *active_comp_image_set_ver_str,
1208 struct variable_field *pending_comp_image_set_ver_str,
1209 struct variable_field *comp_parameter_table);
1210
1211 /** @brief Decode component entries in the component parameter table which is
1212 * part of the response of GetFirmwareParameters command
1213 *
1214 * @param[in] data - Component entry
1215 * @param[in] length - Length of component entry
1216 * @param[out] component_data - Pointer to component parameter table
1217 * @param[out] active_comp_ver_str - Pointer to active component version string
1218 * @param[out] pending_comp_ver_str - Pointer to pending component version
1219 * string
1220 *
1221 * @return pldm_completion_codes
1222 */
1223 int decode_get_firmware_parameters_resp_comp_entry(
1224 const uint8_t *data, size_t length,
1225 struct pldm_component_parameter_entry *component_data,
1226 struct variable_field *active_comp_ver_str,
1227 struct variable_field *pending_comp_ver_str);
1228
1229 /** @brief Encode a GetFirmwareParameters response
1230 *
1231 * @param[in] instance_id - Message's instance id
1232 * @param[in] resp_data - Parameter data
1233 * @param[in,out] msg - Message will be written to this
1234 * @param[in,out] payload_length - Size of the response message payload, updated
1235 * with used length.
1236 *
1237 * @return 0 on success, a negative errno value on failure.
1238 */
1239 int encode_get_firmware_parameters_resp(
1240 uint8_t instance_id,
1241 const struct pldm_get_firmware_parameters_resp_full *resp_data,
1242 struct pldm_msg *msg, size_t *payload_length);
1243
1244 /** @brief Encode a ComponentParameterTable entry
1245 *
1246 * @param[in] comp - Component entry
1247 * @param[in,out] payload - Message will be written to this
1248 * @param[in,out] payload_length - Size of payload, updated
1249 * with used length.
1250 *
1251 * @return 0 on success, a negative errno value on failure.
1252 */
1253 int encode_get_firmware_parameters_resp_comp_entry(
1254 const struct pldm_component_parameter_entry_full *comp,
1255 uint8_t *payload, size_t *payload_length);
1256
1257 /** @brief Create a PLDM request message for QueryDownstreamDevices
1258 *
1259 * @param[in] instance_id - Message's instance id
1260 * @param[out] msg - Message will be written to this
1261 *
1262 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1263 * are not allocated, -EOVERFLOW if the payload length is not enough
1264 * to encode the message, -EBADMSG if the message is not valid.
1265 *
1266 * @note Caller is responsible for memory alloc and dealloc of param
1267 * 'msg.payload'
1268 */
1269 int encode_query_downstream_devices_req(uint8_t instance_id,
1270 struct pldm_msg *msg);
1271
1272 /**
1273 * @brief Decodes the response message for Querying Downstream Devices.
1274 *
1275 * @param[in] msg The PLDM message to decode.
1276 * @param[in] payload_length The length of the message payload.
1277 * @param[out] resp_data Pointer to the structure to store the decoded response data.
1278 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1279 * are not allocated, -EOVERFLOW if the payload length is not enough
1280 * to decode the message, -EBADMSG if the message is not valid.
1281 *
1282 * @note Caller is responsible for memory alloc and dealloc of param
1283 * 'msg.payload'
1284 */
1285 int decode_query_downstream_devices_resp(
1286 const struct pldm_msg *msg, size_t payload_length,
1287 struct pldm_query_downstream_devices_resp *resp_data);
1288
1289 /**
1290 * @brief Encodes a request message for Query Downstream Identifiers.
1291 *
1292 * @param[in] instance_id The instance ID of the PLDM entity.
1293 * @param[in] data_transfer_handle The handle for the data transfer.
1294 * @param[in] transfer_operation_flag The flag indicating the transfer operation.
1295 * @param[out] msg Pointer to the PLDM message structure to store the encoded message.
1296 * @param[in] payload_length The length of the payload.
1297 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1298 * are not allocated, -EOVERFLOW if the payload length is not enough
1299 * to encode the message, -EBADMSG if the message is not valid.
1300 *
1301 * @note Caller is responsible for memory alloc and dealloc of param
1302 * 'msg.payload'
1303 */
1304 int encode_query_downstream_identifiers_req(
1305 uint8_t instance_id,
1306 const struct pldm_query_downstream_identifiers_req *params_req,
1307 struct pldm_msg *msg, size_t payload_length);
1308
1309 /**
1310 * @brief Decodes the response message for Querying Downstream Identifiers.
1311 * @param[in] msg The PLDM message to decode.
1312 * @param[in] payload_length The length of the message payload.
1313 * @param[out] resp_data Pointer to the decoded response data.
1314 * @param[out] iter Pointer to the downstream device iterator structure.
1315 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1316 * are not allocated, -EOVERFLOW if the payload length is not enough
1317 * to decode the message, -EBADMSG if the message is not valid.
1318 *
1319 * @note Caller is responsible for memory alloc and dealloc of pointer params
1320 */
1321 int decode_query_downstream_identifiers_resp(
1322 const struct pldm_msg *msg, size_t payload_length,
1323 struct pldm_query_downstream_identifiers_resp *resp_data,
1324 struct pldm_downstream_device_iter *iter);
1325
1326 /**
1327 * @brief Encodes request message for Get Downstream Firmware Parameters.
1328 *
1329 * @param[in] instance_id - The instance ID of the PLDM entity.
1330 * @param[in] data_transfer_handle - The handle for the data transfer.
1331 * @param[in] transfer_operation_flag - The flag indicating the transfer operation.
1332 * @param[in,out] msg - A pointer to the PLDM message structure to store the encoded message.
1333 * @param[in] payload_length - The length of the payload.
1334 *
1335 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1336 * are not allocated, -EOVERFLOW if the payload length is not enough
1337 * to encode the message, -EBADMSG if the message is not valid.
1338 *
1339 * @note Caller is responsible for memory alloc and dealloc of param
1340 * 'msg.payload'
1341 */
1342 int encode_get_downstream_firmware_parameters_req(
1343 uint8_t instance_id,
1344 const struct pldm_get_downstream_firmware_parameters_req *params_req,
1345 struct pldm_msg *msg, size_t payload_length);
1346
1347 struct pldm_downstream_device_parameters_iter {
1348 struct variable_field field;
1349 size_t entries;
1350 };
1351
1352 /**
1353 * @brief Decode response message for Get Downstream Firmware Parameters
1354 *
1355 * @param[in] msg - The PLDM message to decode
1356 * @param[in] payload_length - The length of the message payload
1357 * @param[out] resp_data - Pointer to the structure to store the decoded response data
1358 * @param[out] downstream_device_param_table - Pointer to the variable field structure
1359 * to store the decoded downstream device
1360 * parameter table
1361 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1362 * are not allocated, -EOVERFLOW if the payload length is not enough
1363 * to decode the message, -EBADMSG if the message is not valid.
1364 *
1365 * @note Caller is responsible for memory alloc and dealloc of param
1366 * 'resp_data' and 'downstream_device_param_table'
1367 */
1368 int decode_get_downstream_firmware_parameters_resp(
1369 const struct pldm_msg *msg, size_t payload_length,
1370 struct pldm_get_downstream_firmware_parameters_resp *resp_data,
1371 struct pldm_downstream_device_parameters_iter *iter);
1372
1373 /**
1374 * @brief Decode the next downstream device parameter table entry
1375 *
1376 * @param[in,out] data - A variable field covering the table entries in the
1377 * response message data. @p data is updated to point to
1378 * the remaining entries once the current entry has been
1379 * decoded.
1380
1381 * @param[out] entry - The struct object into which the current table entry will
1382 * be decoded
1383
1384 * @param[out] versions - A variable field covering the active and
1385 * pending component version strings in the
1386 * response message data. The component version
1387 * strings can be decoded into @p entry using
1388 * decode_downstream_device_parameter_table_entry_versions()
1389 *
1390 * @return 0 on success, otherwise -EINVAL if the input parameters' memory
1391 * are not allocated, -EOVERFLOW if the payload length is not enough
1392 * to decode the entry.
1393 *
1394 * @note Caller is responsible for memory alloc and dealloc of param
1395 * 'entry', 'active_comp_ver_str' and 'pending_comp_ver_str'
1396 */
1397 int decode_pldm_downstream_device_parameters_entry_from_iter(
1398 struct pldm_downstream_device_parameters_iter *iter,
1399 struct pldm_downstream_device_parameters_entry *entry);
1400
1401 LIBPLDM_ITERATOR
pldm_downstream_device_parameters_iter_end(const struct pldm_downstream_device_parameters_iter * iter)1402 bool pldm_downstream_device_parameters_iter_end(
1403 const struct pldm_downstream_device_parameters_iter *iter)
1404 {
1405 return !iter->entries;
1406 }
1407
1408 LIBPLDM_ITERATOR
pldm_downstream_device_parameters_iter_next(struct pldm_downstream_device_parameters_iter * iter)1409 bool pldm_downstream_device_parameters_iter_next(
1410 struct pldm_downstream_device_parameters_iter *iter)
1411 {
1412 if (!iter->entries) {
1413 return false;
1414 }
1415
1416 iter->entries--;
1417 return true;
1418 }
1419
1420 /** @brief Iterator downstream device parameter entries in Get Downstream
1421 * Firmware Parameters response
1422 *
1423 * @param params The @ref "struct pldm_downstream_device_parameters_iter" lvalue
1424 * used as the out-value from the corresponding call to @ref
1425 * decode_get_downstream_firmware_parameters_resp
1426 * @param entry The @ref "struct pldm_downstream_device_parameters_entry" lvalue
1427 * into which the next parameter table entry should be decoded
1428 * @param rc An lvalue of type int into which the return code from the decoding
1429 * will be placed
1430 *
1431 * Example use of the macro is as follows:
1432 *
1433 * @code
1434 * struct pldm_get_downstream_firmware_parameters_resp resp;
1435 * struct pldm_downstream_device_parameters_iter params;
1436 * struct pldm_downstream_device_parameters_entry entry;
1437 * int rc;
1438 *
1439 * rc = decode_get_downstream_firmware_parameters_resp(..., &resp, ¶ms);
1440 * if (rc) {
1441 * // Handle any error from decoding the fixed-portion of response
1442 * }
1443 *
1444 * foreach_pldm_downstream_device_parameters_entry(params, entry, rc) {
1445 * // Do something with the decoded entry
1446 * }
1447 *
1448 * if (rc) {
1449 * // Handle any decoding error while iterating the variable-length set of
1450 * //parameter entries
1451 * }
1452 * @endcode
1453 */
1454 #define foreach_pldm_downstream_device_parameters_entry(params, entry, rc) \
1455 for ((rc) = 0; \
1456 (!pldm_downstream_device_parameters_iter_end(&(params)) && \
1457 !((rc) = decode_pldm_downstream_device_parameters_entry_from_iter( \
1458 &(params), &(entry)))); \
1459 pldm_downstream_device_parameters_iter_next(&(params)))
1460
1461 /** @brief Create PLDM request message for RequestUpdate
1462 *
1463 * @param[in] instance_id - Message's instance id
1464 * @param[in] max_transfer_size - Maximum size of the variable payload allowed
1465 * to be requested via RequestFirmwareData
1466 * command
1467 * @param[in] num_of_comp - Total number of components that will be passed to
1468 * the FD during the update
1469 * @param[in] max_outstanding_transfer_req - Total number of outstanding
1470 * RequestFirmwareData
1471 * commands that can be sent by the FD
1472 * @param[in] pkg_data_len - Value of the FirmwareDevicePackageDataLength field
1473 * present in firmware package header
1474 * @param[in] comp_image_set_ver_str_type - StringType of
1475 * ComponentImageSetVersionString
1476 * @param[in] comp_image_set_ver_str_len - The length of the
1477 * ComponentImageSetVersionString
1478 * @param[in] comp_img_set_ver_str - Component Image Set version information
1479 * @param[in,out] msg - Message will be written to this
1480 * @param[in] payload_length - Length of request message payload
1481 *
1482 * @return pldm_completion_codes
1483 *
1484 * @note Caller is responsible for memory alloc and dealloc of param
1485 * 'msg.payload'
1486 */
1487 int encode_request_update_req(uint8_t instance_id, uint32_t max_transfer_size,
1488 uint16_t num_of_comp,
1489 uint8_t max_outstanding_transfer_req,
1490 uint16_t pkg_data_len,
1491 uint8_t comp_image_set_ver_str_type,
1492 uint8_t comp_image_set_ver_str_len,
1493 const struct variable_field *comp_img_set_ver_str,
1494 struct pldm_msg *msg, size_t payload_length);
1495
1496 /** @brief Decode PLDM request message for RequestUpdate
1497 *
1498 * @param[in] msg - Message
1499 * @param[in] payload_length - Length of request message payload
1500 * @param[out] req - RequestUpdate request parameters
1501 *
1502 * @return 0 on success, a negative errno value on failure.
1503 *
1504 * @note Caller is responsible for memory alloc and dealloc of param
1505 * 'msg.payload'
1506 */
1507 int decode_request_update_req(const struct pldm_msg *msg, size_t payload_length,
1508 struct pldm_request_update_req_full *req);
1509
1510 /** @brief Decode a RequestUpdate response message
1511 *
1512 * @param[in] msg - Response message
1513 * @param[in] payload_length - Length of response message payload
1514 * @param[out] completion_code - Pointer to hold the completion code
1515 * @param[out] fd_meta_data_len - Pointer to hold the length of FD metadata
1516 * @param[out] fd_will_send_pkg_data - Pointer to hold information whether FD
1517 * will send GetPackageData command
1518 * @return pldm_completion_codes
1519 */
1520 int decode_request_update_resp(const struct pldm_msg *msg,
1521 size_t payload_length, uint8_t *completion_code,
1522 uint16_t *fd_meta_data_len,
1523 uint8_t *fd_will_send_pkg_data);
1524
1525 /** @brief Create PLDM response message for RequestUpdate
1526 *
1527 * @param[in] instance_id - Message's instance id
1528 * @param[in] resp_data - Response data
1529 * @param[out] msg - Message will be written to this
1530 * @param[inout] payload_length - Length of response message payload
1531 *
1532 * @return 0 on success, a negative errno value on failure.
1533 *
1534 * @note Caller is responsible for memory alloc and dealloc of param
1535 * 'msg.payload'
1536 */
1537 int encode_request_update_resp(uint8_t instance_id,
1538 const struct pldm_request_update_resp *resp_data,
1539 struct pldm_msg *msg, size_t *payload_length);
1540
1541 /** @brief Create PLDM request message for PassComponentTable
1542 *
1543 * @param[in] instance_id - Message's instance id
1544 * @param[in] transfer_flag - TransferFlag
1545 * @param[in] comp_classification - ComponentClassification
1546 * @param[in] comp_identifier - ComponentIdentifier
1547 * @param[in] comp_classification_index - ComponentClassificationIndex
1548 * @param[in] comp_comparison_stamp - ComponentComparisonStamp
1549 * @param[in] comp_ver_str_type - ComponentVersionStringType
1550 * @param[in] comp_ver_str_len - ComponentVersionStringLength
1551 * @param[in] comp_ver_str - ComponentVersionString
1552 * @param[in,out] msg - Message will be written to this
1553 * @param[in] payload_length - Length of request message payload
1554 * information
1555 *
1556 * @return pldm_completion_codes
1557 *
1558 * @note Caller is responsible for memory alloc and dealloc of param
1559 * 'msg.payload'
1560 */
1561 int encode_pass_component_table_req(
1562 uint8_t instance_id, uint8_t transfer_flag,
1563 uint16_t comp_classification, uint16_t comp_identifier,
1564 uint8_t comp_classification_index, uint32_t comp_comparison_stamp,
1565 uint8_t comp_ver_str_type, uint8_t comp_ver_str_len,
1566 const struct variable_field *comp_ver_str, struct pldm_msg *msg,
1567 size_t payload_length);
1568
1569 /** @brief Decode a PassComponentTable request
1570 *
1571 * @param[in] msg - PLDM Message
1572 * @param[in] payload_length
1573 * @param[out] pcomp - Pass Component Table Request
1574 *
1575 * @return 0 on success, a negative errno value on failure.
1576 */
1577 int decode_pass_component_table_req(
1578 const struct pldm_msg *msg, size_t payload_length,
1579 struct pldm_pass_component_table_req_full *pcomp);
1580
1581 /** @brief Decode PassComponentTable response message
1582 *
1583 * @param[in] msg - Response message
1584 * @param[in] payload_length - Length of response message payload
1585 * @param[out] completion_code - Pointer to hold completion code
1586 * @param[out] comp_resp - Pointer to hold component response
1587 * @param[out] comp_resp_code - Pointer to hold component response code
1588 *
1589 * @return pldm_completion_codes
1590 */
1591 int decode_pass_component_table_resp(const struct pldm_msg *msg,
1592 size_t payload_length,
1593 uint8_t *completion_code,
1594 uint8_t *comp_resp,
1595 uint8_t *comp_resp_code);
1596
1597 /** @brief Encode PassComponentTable response
1598 *
1599 * @param[in] instance_id - PLDM Instance ID matching the request
1600 * @param[in] resp_data - response data
1601 * @param[out] msg - Response message
1602 * @param[inout] payload_length - Length of msg payload buffer,
1603 * will be updated with the written
1604 * length on success.
1605 *
1606 * @return 0 on success, a negative errno value on failure.
1607 */
1608 int encode_pass_component_table_resp(
1609 uint8_t instance_id,
1610 const struct pldm_pass_component_table_resp *resp_data,
1611 struct pldm_msg *msg, size_t *payload_length);
1612
1613 /** @brief Create PLDM request message for UpdateComponent
1614 *
1615 * @param[in] instance_id - Message's instance id
1616 * @param[in] comp_classification - ComponentClassification
1617 * @param[in] comp_identifier - ComponentIdentifier
1618 * @param[in] comp_classification_index - ComponentClassificationIndex
1619 * @param[in] comp_comparison_stamp - ComponentComparisonStamp
1620 * @param[in] comp_image_size - ComponentImageSize
1621 * @param[in] update_option_flags - UpdateOptionFlags
1622 * @param[in] comp_ver_str_type - ComponentVersionStringType
1623 * @param[in] comp_ver_str_len - ComponentVersionStringLength
1624 * @param[in] comp_ver_str - ComponentVersionString
1625 * @param[in,out] msg - Message will be written to this
1626 * @param[in] payload_length - Length of request message payload
1627 * information
1628 *
1629 * @return pldm_completion_codes
1630 *
1631 * @note Caller is responsible for memory alloc and dealloc of param
1632 * 'msg.payload'
1633 */
1634 int encode_update_component_req(
1635 uint8_t instance_id, uint16_t comp_classification,
1636 uint16_t comp_identifier, uint8_t comp_classification_index,
1637 uint32_t comp_comparison_stamp, uint32_t comp_image_size,
1638 bitfield32_t update_option_flags, uint8_t comp_ver_str_type,
1639 uint8_t comp_ver_str_len, const struct variable_field *comp_ver_str,
1640 struct pldm_msg *msg, size_t payload_length);
1641
1642 /** @brief Decode UpdateComponent request message
1643 *
1644 * @param[in] msg - Request message
1645 * @param[in] payload_length - Length of request message payload
1646 * @param[out] up - UpdateComponent request parameters
1647 *
1648 * @return 0 on success, a negative errno value on failure.
1649 */
1650 int decode_update_component_req(const struct pldm_msg *msg,
1651 size_t payload_length,
1652 struct pldm_update_component_req_full *up);
1653
1654 /** @brief Decode UpdateComponent response message
1655 *
1656 * @param[in] msg - Response message
1657 * @param[in] payload_length - Length of response message payload
1658 * @param[out] completion_code - Pointer to hold completion code
1659 * @param[out] comp_compatibility_resp - Pointer to hold component
1660 * compatibility response
1661 * @param[out] comp_compatibility_resp_code - Pointer to hold component
1662 * compatibility response code
1663 * @param[out] update_option_flags_enabled - Pointer to hold
1664 * UpdateOptionsFlagEnabled
1665 * @param[out] time_before_req_fw_data - Pointer to hold the estimated time
1666 * before sending RequestFirmwareData
1667 *
1668 * @return pldm_completion_codes
1669 */
1670 int decode_update_component_resp(const struct pldm_msg *msg,
1671 size_t payload_length,
1672 uint8_t *completion_code,
1673 uint8_t *comp_compatibility_resp,
1674 uint8_t *comp_compatibility_resp_code,
1675 bitfield32_t *update_option_flags_enabled,
1676 uint16_t *time_before_req_fw_data);
1677
1678 /** @brief Encode UpdateComponent response
1679 *
1680 * @param[in] instance_id - PLDM Instance ID matching the request
1681 * @param[in] resp_data - Response data
1682 * @param[out] msg - Response message
1683 * @param[inout] payload_length - Length of msg payload buffer,
1684 * will be updated with the written
1685 * length on success.
1686 *
1687 * @return 0 on success, a negative errno value on failure.
1688 */
1689 int encode_update_component_resp(
1690 uint8_t instance_id, const struct pldm_update_component_resp *resp_data,
1691 struct pldm_msg *msg, size_t *payload_length);
1692
1693 /** @brief Decode RequestFirmwareData request message
1694 *
1695 * @param[in] msg - Request message
1696 * @param[in] payload_length - Length of request message payload
1697 * @param[out] offset - Pointer to hold offset
1698 * @param[out] length - Pointer to hold the size of the component image
1699 * segment requested by the FD/FDP
1700 *
1701 * @return pldm_completion_codes
1702 */
1703 int decode_request_firmware_data_req(const struct pldm_msg *msg,
1704 size_t payload_length, uint32_t *offset,
1705 uint32_t *length);
1706
1707 /** @brief Encode RequestFirmwareData request
1708 *
1709 * @param[in] instance_id - PLDM Instance ID
1710 * @param[in] req_params - Request parameters
1711 * @param[in] length - firmware data length to request
1712 * @param[out] msg - Response message
1713 * @param[inout] payload_length - Length of msg payload buffer,
1714 * will be updated with the written
1715 * length on success.
1716 *
1717 * @return 0 on success, a negative errno value on failure.
1718 */
1719 int encode_request_firmware_data_req(
1720 uint8_t instance_id,
1721 const struct pldm_request_firmware_data_req *req_params,
1722 struct pldm_msg *msg, size_t *payload_length);
1723
1724 /** @brief Create PLDM response message for RequestFirmwareData
1725 *
1726 * The ComponentImagePortion is not encoded in the PLDM response message
1727 * by encode_request_firmware_data_resp to avoid an additional copy. Populating
1728 * ComponentImagePortion in the PLDM response message is handled by the user
1729 * of this API. The payload_length validation considers only the
1730 * CompletionCode.
1731 *
1732 * @param[in] instance_id - Message's instance id
1733 * @param[in] completion_code - CompletionCode
1734 * @param[in,out] msg - Message will be written to this
1735 * @param[in] payload_length - Length of response message payload
1736 *
1737 * @return pldm_completion_codes
1738 *
1739 * @note Caller is responsible for memory alloc and dealloc of param
1740 * 'msg.payload'
1741 */
1742 int encode_request_firmware_data_resp(uint8_t instance_id,
1743 uint8_t completion_code,
1744 struct pldm_msg *msg,
1745 size_t payload_length);
1746
1747 /** @brief Decode TransferComplete request message
1748 *
1749 * @param[in] msg - Request message
1750 * @param[in] payload_length - Length of request message payload
1751 * @param[out] transfer_result - Pointer to hold TransferResult
1752 *
1753 * @return pldm_completion_codes
1754 */
1755 int decode_transfer_complete_req(const struct pldm_msg *msg,
1756 size_t payload_length,
1757 uint8_t *transfer_result);
1758
1759 /** @brief Encode TransferComplete request
1760 *
1761 * @param[in] instance_id - PLDM Instance ID
1762 * @param[in] transfer_result
1763 * @param[out] msg - Response message
1764 * @param[inout] payload_length - Length of msg payload buffer,
1765 * will be updated with the written
1766 * length on success.
1767 *
1768 * @return 0 on success, a negative errno value on failure.
1769 */
1770 int encode_transfer_complete_req(uint8_t instance_id, uint8_t transfer_result,
1771 struct pldm_msg *msg, size_t *payload_length);
1772
1773 /** @brief Create PLDM response message for TransferComplete
1774 *
1775 * @param[in] instance_id - Message's instance id
1776 * @param[in] completion_code - CompletionCode
1777 * @param[in,out] msg - Message will be written to this
1778 * @param[in] payload_length - Length of response message payload
1779 *
1780 * @return pldm_completion_codes
1781 *
1782 * @note Caller is responsible for memory alloc and dealloc of param
1783 * 'msg.payload'
1784 */
1785 int encode_transfer_complete_resp(uint8_t instance_id, uint8_t completion_code,
1786 struct pldm_msg *msg, size_t payload_length);
1787
1788 /** @brief Decode VerifyComplete request message
1789 *
1790 * @param[in] msg - Request message
1791 * @param[in] payload_length - Length of request message payload
1792 * @param[in] verify_result - Pointer to hold VerifyResult
1793 *
1794 * @return pldm_completion_codes
1795 */
1796 int decode_verify_complete_req(const struct pldm_msg *msg,
1797 size_t payload_length, uint8_t *verify_result);
1798
1799 /** @brief Encode VerifyComplete request
1800 *
1801 * @param[in] instance_id - PLDM Instance ID
1802 * @param[in] verify_result
1803 * @param[out] msg - Response message
1804 * @param[inout] payload_length - Length of msg payload buffer,
1805 * will be updated with the written
1806 * length on success.
1807 *
1808 * @return 0 on success, a negative errno value on failure.
1809 */
1810 int encode_verify_complete_req(uint8_t instance_id, uint8_t verify_result,
1811 struct pldm_msg *msg, size_t *payload_length);
1812
1813 /** @brief Create PLDM response message for VerifyComplete
1814 *
1815 * @param[in] instance_id - Message's instance id
1816 * @param[in] completion_code - CompletionCode
1817 * @param[in,out] msg - Message will be written to this
1818 * @param[in] payload_length - Length of response message payload
1819 *
1820 * @return pldm_completion_codes
1821 *
1822 * @note Caller is responsible for memory alloc and dealloc of param
1823 * 'msg.payload'
1824 */
1825 int encode_verify_complete_resp(uint8_t instance_id, uint8_t completion_code,
1826 struct pldm_msg *msg, size_t payload_length);
1827
1828 /** @brief Decode ApplyComplete request message
1829 *
1830 * @param[in] msg - Request message
1831 * @param[in] payload_length - Length of request message payload
1832 * @param[in] apply_result - Pointer to hold ApplyResult
1833 * @param[in] comp_activation_methods_modification - Pointer to hold the
1834 * ComponentActivationMethodsModification
1835 *
1836 * @return pldm_completion_codes
1837 */
1838 int decode_apply_complete_req(
1839 const struct pldm_msg *msg, size_t payload_length,
1840 uint8_t *apply_result,
1841 bitfield16_t *comp_activation_methods_modification);
1842
1843 /** @brief Encode ApplyComplete request
1844 *
1845 * @param[in] instance_id - PLDM Instance ID
1846 * @param[in] req_data - Request data
1847 * @param[out] msg - Request message
1848 * @param[inout] payload_length - Length of msg payload buffer,
1849 * will be updated with the written
1850 * length on success.
1851 *
1852 * @return 0 on success, a negative errno value on failure.
1853 */
1854 int encode_apply_complete_req(uint8_t instance_id,
1855 const struct pldm_apply_complete_req *req_data,
1856 struct pldm_msg *msg, size_t *payload_length);
1857
1858 /** @brief Create PLDM response message for ApplyComplete
1859 *
1860 * @param[in] instance_id - Message's instance id
1861 * @param[in] completion_code - CompletionCode
1862 * @param[in,out] msg - Message will be written to this
1863 * @param[in] payload_length - Length of response message payload
1864 *
1865 * @return pldm_completion_codes
1866 *
1867 * @note Caller is responsible for memory alloc and dealloc of param
1868 * 'msg.payload'
1869 */
1870 int encode_apply_complete_resp(uint8_t instance_id, uint8_t completion_code,
1871 struct pldm_msg *msg, size_t payload_length);
1872
1873 /** @brief Create PLDM request message for ActivateFirmware
1874 *
1875 * @param[in] instance_id - Message's instance id
1876 * @param[in] self_contained_activation_req SelfContainedActivationRequest
1877 * @param[in,out] msg - Message will be written to this
1878 * @param[in] payload_length - Length of request message payload
1879 *
1880 * @return pldm_completion_codes
1881 *
1882 * @note Caller is responsible for memory alloc and dealloc of param
1883 * 'msg.payload'
1884 */
1885 int encode_activate_firmware_req(uint8_t instance_id,
1886 bool8_t self_contained_activation_req,
1887 struct pldm_msg *msg, size_t payload_length);
1888
1889 /** @brief Decode ActivateFirmware request
1890 *
1891 * @param[in] msg - Request message
1892 * @param[in] payload_length - Length of request message payload
1893 * @param[out] self_contained
1894 *
1895 * @return 0 on success, a negative errno value on failure.
1896 */
1897 int decode_activate_firmware_req(const struct pldm_msg *msg,
1898 size_t payload_length, bool *self_contained);
1899
1900 /** @brief Decode ActivateFirmware response message
1901 *
1902 * @param[in] msg - Response message
1903 * @param[in] payload_length - Length of response message payload
1904 * @param[out] completion_code - Pointer to hold CompletionCode
1905 * @param[out] estimated_time_activation - Pointer to hold
1906 * EstimatedTimeForSelfContainedActivation
1907 *
1908 * @return pldm_completion_codes
1909 */
1910 int decode_activate_firmware_resp(const struct pldm_msg *msg,
1911 size_t payload_length,
1912 uint8_t *completion_code,
1913 uint16_t *estimated_time_activation);
1914
1915 /** @brief Encode ActivateFirmware response
1916 *
1917 * @param[in] instance_id - PLDM Instance ID matching the request
1918 * @param[in] resp_data - Response data
1919 * @param[out] msg - Response message
1920 * @param[inout] payload_length - Length of msg payload buffer,
1921 * will be updated with the written
1922 * length on success.
1923 *
1924 * @return 0 on success, a negative errno value on failure.
1925 */
1926 int encode_activate_firmware_resp(
1927 uint8_t instance_id,
1928 const struct pldm_activate_firmware_resp *resp_data,
1929 struct pldm_msg *msg, size_t *payload_length);
1930
1931 /** @brief Create PLDM request message for GetStatus
1932 *
1933 * @param[in] instance_id - Message's instance id
1934 * @param[in,out] msg - Message will be written to this
1935 * @param[in] payload_length - Length of request message payload
1936 *
1937 * @return pldm_completion_codes
1938 *
1939 * @note Caller is responsible for memory alloc and dealloc of param
1940 * 'msg.payload'
1941 */
1942 int encode_get_status_req(uint8_t instance_id, struct pldm_msg *msg,
1943 size_t payload_length);
1944
1945 /** @brief Decode GetStatus response message
1946 *
1947 * @param[in] msg - Response message
1948 * @param[in] payload_length - Length of response message payload
1949 * @param[out] completion_code - Pointer to completion code
1950 * @param[out] current_state - Pointer to current state machine state
1951 * @param[out] previous_state - Pointer to previous different state machine
1952 * state
1953 * @param[out] aux_state - Pointer to current operation state of FD/FDP
1954 * @param[out] aux_state_status - Pointer to aux state status
1955 * @param[out] progress_percent - Pointer to progress percentage
1956 * @param[out] reason_code - Pointer to reason for entering current state
1957 * @param[out] update_option_flags_enabled - Pointer to update option flags
1958 * enabled
1959 *
1960 * @return pldm_completion_codes
1961 */
1962 int decode_get_status_resp(const struct pldm_msg *msg, size_t payload_length,
1963 uint8_t *completion_code, uint8_t *current_state,
1964 uint8_t *previous_state, uint8_t *aux_state,
1965 uint8_t *aux_state_status, uint8_t *progress_percent,
1966 uint8_t *reason_code,
1967 bitfield32_t *update_option_flags_enabled);
1968
1969 /** @brief Encode GetStatus response
1970 *
1971 * @param[in] instance_id - PLDM Instance ID matching the request
1972 * @param[in] status - GetStatus response. completion_code must be PLDM_SUCCESS.
1973 * @param[out] msg - Response message
1974 * @param[inout] payload_length - Length of msg payload buffer,
1975 * will be updated with the written
1976 * length on success.
1977 *
1978 * @return 0 on success, a negative errno value on failure.
1979 */
1980 int encode_get_status_resp(uint8_t instance_id,
1981 const struct pldm_get_status_resp *status,
1982 struct pldm_msg *msg, size_t *payload_length);
1983
1984 /** @brief Create PLDM request message for CancelUpdateComponent
1985 *
1986 * @param[in] instance_id - Message's instance id
1987 * @param[in,out] msg - Message will be written to this
1988 * @param[in] payload_length - Length of request message payload
1989 *
1990 * @return pldm_completion_codes
1991 *
1992 * @note Caller is responsible for memory alloc and dealloc of param
1993 * 'msg.payload'
1994 */
1995 int encode_cancel_update_component_req(uint8_t instance_id,
1996 struct pldm_msg *msg,
1997 size_t payload_length);
1998
1999 /** @brief Decode CancelUpdateComponent response message
2000 *
2001 * @param[in] msg - Response message
2002 * @param[in] payload_length - Length of response message payload
2003 * @param[out] completion_code - Pointer to the completion code
2004 *
2005 * @return pldm_completion_codes
2006 */
2007 int decode_cancel_update_component_resp(const struct pldm_msg *msg,
2008 size_t payload_length,
2009 uint8_t *completion_code);
2010
2011 /** @brief Create PLDM request message for CancelUpdate
2012 *
2013 * @param[in] instance_id - Message's instance id
2014 * @param[in,out] msg - Message will be written to this
2015 * @param[in] payload_length - Length of request message payload
2016 *
2017 * @return pldm_completion_codes
2018 *
2019 * @note Caller is responsible for memory alloc and dealloc of param
2020 * 'msg.payload'
2021 */
2022 int encode_cancel_update_req(uint8_t instance_id, struct pldm_msg *msg,
2023 size_t payload_length);
2024
2025 /** @brief Decode CancelUpdate response message
2026 *
2027 * @param[in] msg - Response message
2028 * @param[in] payload_length - Length of response message payload
2029 * @param[out] completion_code - Pointer to completion code
2030 * @param[out] non_functioning_component_indication - Pointer to non
2031 functioning
2032 * component indication
2033 * @param[out] non_functioning_component_bitmap - Pointer to non
2034 functioning
2035 * component bitmap
2036 *
2037 * @return pldm_completion_codes
2038 */
2039 int decode_cancel_update_resp(const struct pldm_msg *msg, size_t payload_length,
2040 uint8_t *completion_code,
2041 bool8_t *non_functioning_component_indication,
2042 bitfield64_t *non_functioning_component_bitmap);
2043
2044 /** @brief Encode CancelUpdate response
2045 *
2046 * @param[in] instance_id - PLDM Instance ID matching the request
2047 * @param[in] resp_data - Response data,
2048 * @param[out] msg - Response message
2049 * @param[inout] payload_length - Length of msg payload buffer,
2050 * will be updated with the written
2051 * length on success.
2052 *
2053 * @return 0 on success, a negative errno value on failure.
2054 */
2055 int encode_cancel_update_resp(uint8_t instance_id,
2056 const struct pldm_cancel_update_resp *resp_data,
2057 struct pldm_msg *msg, size_t *payload_length);
2058
2059 #ifdef __cplusplus
2060 }
2061 #endif
2062
2063 #endif // End of FW_UPDATE_H
2064