1# Changelog 2 3All notable changes to this project will be documented in this file. 4 5The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6and this project adheres to 7[Semantic Versioning](https://semver.org/spec/v2.0.0.html). 8 9Change categories: 10 11- Added 12- Changed 13- Deprecated 14- Removed 15- Fixed 16- Security 17 18## [Unreleased] 19 20### Added 21 221. oem: meta: Add decode_oem_meta_file_io_write_req() 232. oem: meta: Add decode_oem_meta_file_io_read_req() 243. oem: meta: Add encode_oem_meta_file_io_read_resp() 254. pdr: Add pldm_entity_association_pdr_remove_contained_entity() 265. pdr: Add pldm_pdr_remove_fru_record_set_by_rsi() 276. pldm_entity_association_tree_copy_root_check() 28 29### Changed 30 311. dsp: bios_table: Null check for pldm_bios_table_iter_is_end() 32 33 pldm_bios_table_iter_is_end() now returns true if the provided argument is 34 NULL. 35 362. ABI break for pldm_pdr_find_record() 37 38 Register assignment for function parameters was changed with the removal of 39 some asserts in related implementations. 40 413. ABI break for pldm_pdr_get_next_record() 42 43 Register assignment for function parameters was changed with the removal of 44 some asserts in related implementations. 45 46### Deprecated 47 481. oem: meta: Deprecate `decode_oem_meta_file_io_req()` 49 50 Users should switch to `decode_oem_meta_file_io_write_req()`. Modify this 51 function to make it safer. 52 53 Modification: 54 55 - The meaning of the returned result. 56 - Change parameters from individual pointers to a struct. 57 - Check the length provided in the message won't exceed the buffer. 58 592. pldm_entity_association_tree_copy_root() 60 61 The implementation allocates, but gives no indication to the caller if an 62 allocation (and hence the copy) has failed. Users should migrate to 63 pldm_entity_association_tree_copy_root_check(). 64 65### Removed 66 671. Deprecated functions with the `_check` suffix 68 69 - `get_fru_record_by_option_check()` 70 - `pldm_bios_table_append_pad_checksum_check()` 71 - `pldm_bios_table_attr_entry_enum_decode_def_num_check()` 72 - `pldm_bios_table_attr_entry_enum_decode_pv_hdls_check()` 73 - `pldm_bios_table_attr_entry_enum_decode_pv_num_check()` 74 - `pldm_bios_table_attr_entry_enum_encode_check()` 75 - `pldm_bios_table_attr_entry_integer_encode_check()` 76 - `pldm_bios_table_attr_entry_string_decode_def_string_length_check()` 77 - `pldm_bios_table_attr_entry_string_encode_check()` 78 - `pldm_bios_table_attr_value_entry_encode_enum_check()` 79 - `pldm_bios_table_attr_value_entry_encode_integer_check()` 80 - `pldm_bios_table_attr_value_entry_encode_string_check()` 81 - `pldm_bios_table_string_entry_decode_string_check()` 82 - `pldm_bios_table_string_entry_encode_check()` 83 - `pldm_entity_association_pdr_add_check()` 84 - `pldm_entity_association_pdr_add_from_node_check()` 85 - `pldm_pdr_add_check()` 86 - `pldm_pdr_add_fru_record_set_check()` 87 88### Fixed 89 901. dsp: bios_table: Null check for pldm_bios_table_iter_is_end() 91 92 Avoid a caller-controlled NULL pointer dereference in the library 93 implementation. 94 95## [0.9.1] - 2024-09-07 96 97### Changed 98 991. Moved evolutions intended for v0.9.0 into place 100 101 Evolutions for the release have been moved from `evolutions/current` to 102 `evolutions/v0.9.1`. Library users can apply them to migrate off of 103 deprecated APIs. 104 105## [0.9.0] - 2024-09-07 106 107### Added 108 1091. base: Define macros for reserved TIDs 1102. pdr: Add pldm_entity_association_pdr_add_contained_entity_to_remote_pdr() 1113. pdr: Add pldm_entity_association_pdr_create_new() 1124. platform: Define macros for the responded transferflags 1135. pdr: Add pldm_pdr_get_terminus_handle() API 1146. pdr: Add related decode_entity_auxiliary_names_pdr() APIs 1157. fw_update: Add encode req & decode resp for get_downstream_fw_params 1168. platform: Add decode_pldm_platform_cper_event() API 1179. decode_get_pdr_repository_info_resp_safe() 118 119 Replaces decode_get_pdr_repository_info_resp() as discussed in the 120 `Deprecated` section below 121 12210. decode_get_pdr_resp_safe() 123 124 Replaces decode_get_pdr_resp() as discussed in the `Deprecated` section 125 below 126 127### Changed 128 1291. pdr: Stabilise related decode_entity_auxiliary_names_pdr() APIs 1302. platform: Rework decode/encode_pldm_message_poll_event_data() APIs 1313. platform: Stabilise decode_pldm_message_poll_event_data() APIs 1324. ABI break for decode_sensor_op_data() 133 134 Applying LIBPLDM_CC_NONNULL to the internal msgbuf APIs caused 135 abi-compliance-checker to flag a change in the register containing the 136 parameter `previous_op_state`. 137 1385. platform: Stabilise decode_pldm_platform_cper_event() API 139 140### Deprecated 141 1421. Rename and deprecate functions with the `_check` suffix 143 144 All library function return values always need to be checked. The `_check` 145 suffix is redundant, so remove it. Migration to the non-deprecated 146 equivalents without the `_check` suffix can be performed using 147 `scripts/ apply-renames` and the [clang-rename][] configurations under 148 `evolutions/` 149 150 The deprecated functions: 151 152 - `get_fru_record_by_option_check()` 153 - `pldm_bios_table_append_pad_checksum_check()` 154 - `pldm_bios_table_attr_entry_enum_decode_def_num_check()` 155 - `pldm_bios_table_attr_entry_enum_decode_pv_hdls_check()` 156 - `pldm_bios_table_attr_entry_enum_decode_pv_num_check()` 157 - `pldm_bios_table_attr_entry_enum_encode_check()` 158 - `pldm_bios_table_attr_entry_integer_encode_check()` 159 - `pldm_bios_table_attr_entry_string_decode_def_string_length_check()` 160 - `pldm_bios_table_attr_entry_string_encode_check()` 161 - `pldm_bios_table_attr_value_entry_encode_enum_check()` 162 - `pldm_bios_table_attr_value_entry_encode_integer_check()` 163 - `pldm_bios_table_attr_value_entry_encode_string_check()` 164 - `pldm_bios_table_string_entry_decode_string_check()` 165 - `pldm_bios_table_string_entry_encode_check()` 166 - `pldm_entity_association_pdr_add_check()` 167 - `pldm_entity_association_pdr_add_from_node_check()` 168 - `pldm_pdr_add_check()` 169 - `pldm_pdr_add_fru_record_set_check()` 170 171[clang-rename]: https://clang.llvm.org/extra/clang-rename.html 172 1732. `decode_get_pdr_repository_info_resp()` 174 175 Users should move to `decode_get_pdr_repository_info_resp_safe()` which 176 eliminates the opportunity for buffer overruns when extracting objects from 177 the message. 178 1793. `decode_get_pdr_resp()` 180 181 Users should move to `decode_get_pdr_resp_safe()` which reduces the 182 invocation tedium and improves memory safety over `decode_get_pdr_resp()`. 183 184### Removed 185 1861. IBM OEM header compatibility symlinks. 187 188 Anyone left using the deprecated paths can migrate using the coccinelle patch 189 at `evolutions/current/oem-ibm-header-compat.cocci`. 190 191### Fixed 192 1931. requester: instance-id: Release read lock on conflict 194 195## [0.8.0] - 2024-05-23 196 197### Added 198 1991. base: Provide pldm_msg_hdr_correlate_response() 2002. transport: af-mctp: Add pldm_transport_af_mctp_bind() 2013. oem: ibm: Add chapdata file type support 2024. base: Added PLDM_SMBIOS & PLDM_RDE message types 2035. oem: meta: Add decode_oem_meta_file_io_req() 2046. state-set: Add all state set values to system power state enum as per DSP0249 2057. platform: Add alias members to the enum 206 pldm_pdr_repository_chg_event_change_record_event_data_operation. 207 208 enum constants with inconsistent names are deprecated with this change. 209 remove old inconsistent enum members after backward compatibility cleanup is 210 done 211 2128. oem-ibm: Alias `pldm_oem_ibm_fru_field_type` members as `PLDM_OEM_IBM_*` 2139. oem: ibm: Add Firmware Update Access Key(UAK) as a FRU field type 21410. platform: Add 3 PDR type enum for Redfish Device Enablement per 215 DSP0248_1.2.0 21611. state_set: Add CONNECTED and DISCONNECTED enum for Link State set 21712. entity: Add enum for Network Interface Connectors and Network Ports 218 Connection Types 21913. pdr: Add decode_numeric_effecter_pdr_data() 22014. oem: ibm: Support for the Real SAI entity id 22115. fw_update: Add encode req & decode resp for query_downstream_devices 22216. fw_update: Add encode req & decode resp for query_downstream_identifiers 22317. platform: Add support for GetStateEffecterStates command 224 225### Changed 226 2271. base: Stabilise pldm_msg_hdr_correlate_response() 2282. transport: af-mctp: Stabilise pldm_transport_af_mctp_bind() 2293. libpldm: Fix header use 2304. libpldm: More fixes for header use 2315. pdr: Stabilise pldm_pdr_find_last_in_range() API 2326. pdr: Stabilise pldm_entity_association_pdr_add_from_node_with_record_handle() 2337. oem: meta: stabilise decode_oem_meta_file_io_req() 2348. pdr: pldm_entity_association_tree_copy_root(): Document preconditions 235 236### Deprecated 237 2381. Deprecate `pldm_oem_ibm_fru_field_type` members that that are not prefixed 239 with `PLDM_OEM_IBM_` 240 241### Fixed 242 2431. libpldm: Rationalise the local and installed path of pldm.h 2442. pdr: Assign record_handle in entity_association_pdr_add_children() 2453. msgbuf: Require sensor data enum in pldm_msgbuf_extract_sensor_value() 2464. pdr: Remove redundant constant for minimum numeric sensor PDR length 2475. tests: oem: meta: Fix fileio use of msgbuf 248 249## [0.7.0] - 2023-08-29 250 251### Added 252 2531. state-set: Add new enum for Operational Fault Status enum 254 255### Changed 256 2571. transport: Match specified metadata in pldm_transport_send_recv_msg() 2582. transport: mctp-demux: Drop ABI annotation for internal symbols 2593. transport: Stabilise core transport and implementation APIs 260 261 This stabilisation covers the following headers and functions: 262 263 - libpldm/transport.h 264 265 - pldm_transport_poll() 266 - pldm_transport_send_msg() 267 - pldm_transport_recv_msg() 268 - pldm_transport_send_recv_msg() 269 270 - libpldm/transport/af-mctp.h 271 272 - pldm_transport_af_mctp_init() 273 - pldm_transport_af_mctp_destroy() 274 - pldm_transport_af_mctp_core() 275 - pldm_transport_af_mctp_init_pollfd() 276 - pldm_transport_af_mctp_map_tid() 277 - pldm_transport_af_mctp_unmap_tid() 278 279 - libpldm/transport/mctp-demux.h 280 - pldm_transport_mctp_demux_init() 281 - pldm_transport_mctp_demux_destroy() 282 - pldm_transport_mctp_demux_core() 283 - pldm_transport_mctp_demux_init_pollfd() 284 - pldm_transport_mctp_demux_map_tid() 285 - pldm_transport_mctp_demux_unmap_tid() 286 287### Deprecated 288 2891. All the existing "requester" APIs from `libpldm/pldm.h` (also known as 290 `libpldm/requester/pldm.h`): 291 292 - pldm_open() 293 - pldm_send_recv() 294 - pldm_send() 295 - pldm_recv() 296 - pldm_recv_any() 297 - pldm_close() 298 299 Users should migrate to the newer "transport" APIs instead. 300 301## Fixed 302 3031. tests: Exclude transport tests when build excludes testing ABIs 3042. abi: Capture deprecation of pldm_close() 305 306## [0.6.0] - 2023-08-22 307 308### Changed 309 3101. pdr: Avoid ID overflow in pldm_entity_association_tree_add_entity() 3112. meson: Apply `b_ndebug=if-release` by default 3123. pdr : Stabilize pldm_entity_association_tree_add_entity() 3134. pdr: Stabilise pldm_entity_association_tree_find_with_locality() 3145. pdr: Stabilize pldm_entity_node_get_remote_container_id() 3156. transport: af-mctp: Assign out-params on success in \*\_recv() 3167. transport: Generalise the pldm_transport_recv_msg() API 317 318### Removed 319 3201. pdr: Remove pldm_entity_association_pdr_add() 3212. state-set: Remove enum pldm_state_set_operational_fault_status_values 322 323### Fixed 324 3251. transport: register init_pollfd callback for af-mctp 3262. transport: fix init_pollfd function parameter 3273. transport: Fix doxygen and variables for send and recv functions 3284. transport: af-mctp: Ensure malloc() succeeds in \*\_recv() 329 330## [0.5.0] - 2023-08-09 331 332### Added 333 3341. pdr: Introduce pldm_entity_association_pdr_add_check() 335 336### Changed 337 3381. pdr: Allow record_handle to be NULL for pldm_pdr_add_check() 3392. transport: pldm_transport_poll(): Adjust return value semantics 3403. transport: free un-wanted responses in pldm_transport_send_recv_msg() 341 342### Deprecated 343 3441. state-set: Enum pldm_state_set_operational_fault_status_values 345 346 The enum operational_fault_status is defined with wrong members and will 347 eventually be replaced with the correct members. Any uses of 348 pldm_state_set_operational_fault_status_values members should move to 349 equivalent pldm_state_set_operational_stress_status_values members if needed. 350 3512. platform: Struct field name in fru_record_set PDR 352 353 References to entity_instance_num should be changed to entity_instance 354 3553. platform: Struct field name in numeric sensor value PDR 356 357 References to entity_instance_num should be changed to entity_instance 358 359### Removed 360 3611. bios_table: Remove pldm_bios_table_attr_entry_integer_encode_length() 3622. bios_table: Remove pldm_bios_table_attr_value_entry_encode_enum() 3633. bios_table: Remove pldm_bios_table_attr_value_entry_encode_string() 3644. bios_table: Remove pldm_bios_table_attr_value_entry_encode_integer() 3655. bios_table: Remove pldm_bios_table_append_pad_checksum() 3666. fru: Remove get_fru_record_by_option() 3677. pdr: Make is_present() static 3688. pdr: Remove pldm_pdr_add() 3699. pdr: Remove pldm_pdr_add_fru_record_set() 37010. pdr: Remove pldm_entity_association_pdr_add_from_node() 37111. pdr: Make find_entity_ref_in_tree() static 37212. pdr: Make entity_association_tree_find() static 373 374### Fixed 375 3761. requester: Fix response buffer cast in pldm_send_recv() 3772. pdr: Hoist record handle overflow test to avoid memory leak 3783. transport: Correct comparison in while loop condition 379 380## [0.4.0] - 2023-07-14 381 382### Added 383 3841. bios_table: Introduce pldm_bios_table_append_pad_checksum_check() 3852. fru: Introduce get_fru_record_by_option_check() 3863. pdr: Introduce pldm_entity_association_pdr_add_from_node_check() 3874. pdr: Introduce pldm_pdr_add_check() 3885. pdr: Introduce pldm_pdr_add_fru_record_set_check() 389 390### Changed 391 3921. requester: Mark pldm_close() as LIBPLDM_ABI_TESTING 3932. requester: Expose pldm_close() in header 3943. bios_table: pldm_bios_table_string_entry_encode_check(): Handle overflow 3954. bios_table: pldm_bios_table_iter_create(): Return NULL on failed alloc 3965. bios_table: pldm_bios_table_iter_next(): Invalid entry halts iteration 3976. pdr: pldm_pdr_init(): Return NULL on allocation failure 3987. pdr: pldm_pdr_destroy(): Exit early if repo is NULL 3998. pdr: Document preconditions for trivial accessor functions 400 401 A trivial accessor function is one that exposes properties of an object in a 402 way can't result in an error, beyond passing an invalid argument to the 403 function. For APIs meeting this definition we define a precondition that 404 struct pointers must point to valid objects to avoid polluting the function 405 prototypes. The following APIs now have this precondition explicitly defined: 406 407 - pldm_entity_extract() 408 - pldm_entity_get_parent() 409 - pldm_entity_is_exist_parent() 410 - pldm_entity_is_node_parent() 411 - pldm_is_current_parent_child 412 - pldm_is_empty_entity_assoc_tree() 413 - pldm_pdr_get_record_count() 414 - pldm_pdr_get_record_handle() 415 - pldm_pdr_get_repo_size() 416 - pldm_pdr_record_is_remote() 417 4189. pdr: pldm_entity_node_get_remote_container_id() is a trivial accessor 41910. pdr: pldm_pdr_fru_record_set_find_by_rsi(): Exit early on NULL arguments 42011. pdr: pldm_entity_association_tree_init(): Return NULL on failed alloc 42112. pdr: pldm_entity_association_tree_visit(): Document preconditions 42213. pdr: pldm_entity_association_tree_visit(): Exit early on failure 42314. pdr: pldm_entity_association_tree_destroy(): Exit early on bad argument 42415. pdr: pldm_entity_get_num_children(): Return zero for invalid arguments 42516. pdr: pldm_is_current_parent_child(): Return false for invalid arguments 42617. pdr: pldm_entity_association_pdr_add(): Exit early on bad arguments 42718. pdr: pldm_find_entity_ref_in_tree(): Exit early on bad arguments 42819. pdr: pldm_entity_association_tree_find(): Early exit on bad arguments 42920. pdr: pldm_entity_association_tree_destroy_root(): Exit early on bad arg 43021. pdr: pldm_entity_association_pdr_extract(): Early exit on bad arguments 43122. pdr: pldm_entity_association_pdr_extract(): Assign out params at exit 43223. pdr: pldm_entity_get_num_children(): Don't return invalid values 43324. libpldm: Lift or remove asserts where a subsequent check exists 434 435### Deprecated 436 4371. pldm_bios_table_attr_entry_integer_encode() 438 439 Migrate to pldm_bios_table_attr_entry_integer_encode_check() 440 4412. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_enum() 442 443 Migrate to pldm_bios_table_attr_value_entry_encode_enum_check() 444 4453. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_string() 446 447 Migrate to pldm_bios_table_attr_value_entry_encode_string_check() 448 4494. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_integer() 450 451 Migrate to pldm_bios_table_attr_value_entry_encode_integer_check() 452 4535. pdr: Deprecate is_present() 454 455 There should be no users of this symbol. If you are a user, you should figure 456 out how to stop, or get in touch. This symbol will be marked static the 457 release after deprecation. 458 4596. pdr: Deprecate find_entity_ref_in_tree() 460 461 There should be no users of this symbol. If you are a user, you should figure 462 out how to stop, or get in touch. This symbol will be marked static the 463 release after deprecation. 464 4657. pdr: Deprecate entity_association_tree_find() 466 467 There should be no users of this symbol. If you are a user, you should figure 468 out how to stop, or get in touch. This symbol will be marked static the 469 release after deprecation. 470 4718. bios_table: Stabilise pldm_bios_table_append_pad_checksum_check() 472 473 pldm_bios_table_append_pad_checksum() is deprecated by this change. Users of 474 pldm_bios_table_append_pad_checksum() should migrate to 475 pldm_bios_table_append_pad_checksum_check() 476 4779. fru: Stabilise get_fru_record_by_option_check() 478 479 get_fru_record_by_option() is deprecated by this change. Users of 480 get_fru_record_by_option() should migrate to get_fru_record_by_option_check() 481 48210. pdr: Stabilise pldm_entity_association_pdr_add_from_node_check() 483 484 pldm_entity_association_pdr_add_from_node() is deprecated by this change. 485 Users of pldm_entity_association_pdr_add_from_node() should migrate to 486 pldm_entity_association_pdr_add_from_node_check() 487 48811. pdr: Stabilise pldm_pdr_add_check() 489 490 pldm_pdr_add() is deprecated by this change. Users of pldm_pdr_add() should 491 migrate to pldm_pdr_add_check() 492 49312. pdr: Stabilise pldm_pdr_add_fru_record_set_check() 494 495 pldm_pdr_add_fru_record_set() is deprecated by this change. Users of 496 pldm_pdr_add_fru_record_set() should migrate to 497 pldm_pdr_add_fru_record_set_check() 498 499### Removed 500 5011. bios_table: Remove deprecated APIs sanitized by assert(): 502 503 - pldm_bios_table_string_entry_encode() 504 - pldm_bios_table_string_entry_decode_string() 505 - pldm_bios_table_attr_entry_enum_encode() 506 - pldm_bios_table_attr_entry_enum_decode_pv_num() 507 - pldm_bios_table_attr_entry_enum_decode_def_num() 508 - pldm_bios_table_attr_entry_enum_decode_pv_hdls() 509 - pldm_bios_table_attr_entry_string_encode() 510 - pldm_bios_table_attr_entry_string_decode_def_string_length() 511 512### Fixed 513 5141. pdr: Return success for pldm_pdr_find_child_container_id_range_exclude() API 5152. pdr: Rework pldm_pdr_find_container_id_range_exclude() API 5163. transport: mctp-demux: Don't test socket for non-zero value 5174. requester: Return PLDM_REQUESTER_OPEN_FAIL from pldm_open() on error 5185. pdr: pldm_pdr_fru_record_set_find_by_rsi(): Document reality of return 5196. transport: Fix possible NULL ptr deref in pldm_socket_sndbuf_init() 5207. abi: Update to remove pldm_close() from reference dumps 5218. bios_table: Annotate pldm_bios_table_attr_value_entry_encode_integer() 522 523## [0.3.0] - 2023-06-23 524 525### Added 526 5271. Add encode/decode pldmMessagePollEvent data 5282. README: Add a section on working with libpldm 5293. pdr: Introduce remote_container_id and associated APIs 5304. pdr: Add APIs for creating and locating remote PDRs 5315. pdr: Add pldm_pdr_find_last_in_range() 5326. pdr: Add pldm_entity_association_pdr_add_from_node_with_record_handle() 5337. pdr: Add pldm_pdr_find_container_id_range_exclude() 534 535### Changed 536 5371. include: Move installed transport.h under libpldm/ 5382. libpldm: Explicit deprecated, stable and testing ABI classes 5393. meson: Reduce strength of oem-ibm requirements from enabled to allowed 540 541 The `oem-ibm` feature is now enabled by the default meson configuration, for 542 CI purposes. `oem-ibm` is still disabled by default in the `libpldm` bitbake 543 recipe: 544 545 <https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/libpldm/libpldm_git.bb#L10> 546 547 To disable `oem-ibm` in your development builds, pass `-Doem-ibm=disabled` 548 when invoking `meson setup` 549 5504. bios_table: Relax pldm_bios_table_string_entry_decode_string_check() 5515. bios_table: Relax pldm_bios_table_attr_entry_enum_decode_pv_hdls_check() 552 553### Deprecated 554 5551. bios_table: Deprecate APIs with arguments sanitized using assert() 556 557 C provides enough foot-guns without us encoding them into library APIs. 558 Specifically, deprecate the following in favour of their `*_check()` variants 559 which ensure assertions won't fail or otherwise invoke UB: 560 561 - pldm_bios_table_string_entry_encode() 562 - pldm_bios_table_string_entry_decode_string() 563 - pldm_bios_table_attr_entry_enum_encode() 564 - pldm_bios_table_attr_entry_enum_decode_pv_num() 565 - pldm_bios_table_attr_entry_enum_decode_def_num() 566 - pldm_bios_table_attr_entry_enum_decode_pv_hdls() 567 - pldm_bios_table_attr_entry_string_encode() 568 - pldm_bios_table_attr_entry_string_decode_def_string_length() 569 570### Removed 571 5721. libpldm: Remove the requester-api option 573 574### Fixed 575 5761. requester: Make pldm_open() return existing fd 5772. transport: Prevent sticking in waiting for response 5783. transport: Match on response in pldm_transport_send_recv_msg() 5794. requester: Add check before accessing hdr in pldm_recv() 5805. bios_table: pldm_bios_table_attr_entry_string_info_check() NULL deref 581