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### Removed 21 221. Deprecated functions with the `_check` suffix 23 24 - `pldm_bios_table_append_pad_checksum_check()` 25 - `pldm_bios_table_attr_entry_enum_decode_def_num_check()` 26 - `pldm_bios_table_attr_entry_enum_decode_pv_hdls_check()` 27 - `pldm_bios_table_attr_entry_enum_decode_pv_num_check()` 28 - `pldm_bios_table_attr_entry_enum_encode_check()` 29 - `pldm_bios_table_attr_entry_integer_encode_check()` 30 31## [0.9.1] - 2024-09-07 32 33### Changed 34 351. Moved evolutions intended for v0.9.0 into place 36 37 Evolutions for the release have been moved from `evolutions/current` to 38 `evolutions/v0.9.1`. Library users can apply them to migrate off of 39 deprecated APIs. 40 41## [0.9.0] - 2024-09-07 42 43### Added 44 451. base: Define macros for reserved TIDs 462. pdr: Add pldm_entity_association_pdr_add_contained_entity_to_remote_pdr() 473. pdr: Add pldm_entity_association_pdr_create_new() 484. platform: Define macros for the responded transferflags 495. pdr: Add pldm_pdr_get_terminus_handle() API 506. pdr: Add related decode_entity_auxiliary_names_pdr() APIs 517. fw_update: Add encode req & decode resp for get_downstream_fw_params 528. platform: Add decode_pldm_platform_cper_event() API 539. decode_get_pdr_repository_info_resp_safe() 54 55 Replaces decode_get_pdr_repository_info_resp() as discussed in the 56 `Deprecated` section below 57 5810. decode_get_pdr_resp_safe() 59 60 Replaces decode_get_pdr_resp() as discussed in the `Deprecated` section 61 below 62 63### Changed 64 651. pdr: Stabilise related decode_entity_auxiliary_names_pdr() APIs 662. platform: Rework decode/encode_pldm_message_poll_event_data() APIs 673. platform: Stabilise decode_pldm_message_poll_event_data() APIs 684. ABI break for decode_sensor_op_data() 69 70 Applying LIBPLDM_CC_NONNULL to the internal msgbuf APIs caused 71 abi-compliance-checker to flag a change in the register containing the 72 parameter `previous_op_state`. 73 745. platform: Stabilise decode_pldm_platform_cper_event() API 75 76### Deprecated 77 781. Rename and deprecate functions with the `_check` suffix 79 80 All library function return values always need to be checked. The `_check` 81 suffix is redundant, so remove it. Migration to the non-deprecated 82 equivalents without the `_check` suffix can be performed using 83 `scripts/ apply-renames` and the [clang-rename][] configurations under 84 `evolutions/` 85 86 The deprecated functions: 87 88 - `get_fru_record_by_option_check()` 89 - `pldm_bios_table_append_pad_checksum_check()` 90 - `pldm_bios_table_attr_entry_enum_decode_def_num_check()` 91 - `pldm_bios_table_attr_entry_enum_decode_pv_hdls_check()` 92 - `pldm_bios_table_attr_entry_enum_decode_pv_num_check()` 93 - `pldm_bios_table_attr_entry_enum_encode_check()` 94 - `pldm_bios_table_attr_entry_integer_encode_check()` 95 - `pldm_bios_table_attr_entry_string_decode_def_string_length_check()` 96 - `pldm_bios_table_attr_entry_string_encode_check()` 97 - `pldm_bios_table_attr_value_entry_encode_enum_check()` 98 - `pldm_bios_table_attr_value_entry_encode_integer_check()` 99 - `pldm_bios_table_attr_value_entry_encode_string_check()` 100 - `pldm_bios_table_string_entry_decode_string_check()` 101 - `pldm_bios_table_string_entry_encode_check()` 102 - `pldm_entity_association_pdr_add_check()` 103 - `pldm_entity_association_pdr_add_from_node_check()` 104 - `pldm_pdr_add_check()` 105 - `pldm_pdr_add_fru_record_set_check()` 106 107[clang-rename]: https://clang.llvm.org/extra/clang-rename.html 108 1092. `decode_get_pdr_repository_info_resp()` 110 111 Users should move to `decode_get_pdr_repository_info_resp_safe()` which 112 eliminates the opportunity for buffer overruns when extracting objects from 113 the message. 114 1153. `decode_get_pdr_resp()` 116 117 Users should move to `decode_get_pdr_resp_safe()` which reduces the 118 invocation tedium and improves memory safety over `decode_get_pdr_resp()`. 119 120### Removed 121 1221. IBM OEM header compatibility symlinks. 123 124 Anyone left using the deprecated paths can migrate using the coccinelle patch 125 at `evolutions/current/oem-ibm-header-compat.cocci`. 126 127### Fixed 128 1291. requester: instance-id: Release read lock on conflict 130 131## [0.8.0] - 2024-05-23 132 133### Added 134 1351. base: Provide pldm_msg_hdr_correlate_response() 1362. transport: af-mctp: Add pldm_transport_af_mctp_bind() 1373. oem: ibm: Add chapdata file type support 1384. base: Added PLDM_SMBIOS & PLDM_RDE message types 1395. oem: meta: Add decode_oem_meta_file_io_req() 1406. state-set: Add all state set values to system power state enum as per DSP0249 1417. platform: Add alias members to the enum 142 pldm_pdr_repository_chg_event_change_record_event_data_operation. 143 144 enum constants with inconsistent names are deprecated with this change. 145 remove old inconsistent enum members after backward compatibility cleanup is 146 done 147 1488. oem-ibm: Alias `pldm_oem_ibm_fru_field_type` members as `PLDM_OEM_IBM_*` 1499. oem: ibm: Add Firmware Update Access Key(UAK) as a FRU field type 15010. platform: Add 3 PDR type enum for Redfish Device Enablement per 151 DSP0248_1.2.0 15211. state_set: Add CONNECTED and DISCONNECTED enum for Link State set 15312. entity: Add enum for Network Interface Connectors and Network Ports 154 Connection Types 15513. pdr: Add decode_numeric_effecter_pdr_data() 15614. oem: ibm: Support for the Real SAI entity id 15715. fw_update: Add encode req & decode resp for query_downstream_devices 15816. fw_update: Add encode req & decode resp for query_downstream_identifiers 15917. platform: Add support for GetStateEffecterStates command 160 161### Changed 162 1631. base: Stabilise pldm_msg_hdr_correlate_response() 1642. transport: af-mctp: Stabilise pldm_transport_af_mctp_bind() 1653. libpldm: Fix header use 1664. libpldm: More fixes for header use 1675. pdr: Stabilise pldm_pdr_find_last_in_range() API 1686. pdr: Stabilise pldm_entity_association_pdr_add_from_node_with_record_handle() 1697. oem: meta: stabilise decode_oem_meta_file_io_req() 1708. pdr: pldm_entity_association_tree_copy_root(): Document preconditions 171 172### Deprecated 173 1741. Deprecate `pldm_oem_ibm_fru_field_type` members that that are not prefixed 175 with `PLDM_OEM_IBM_` 176 177### Fixed 178 1791. libpldm: Rationalise the local and installed path of pldm.h 1802. pdr: Assign record_handle in entity_association_pdr_add_children() 1813. msgbuf: Require sensor data enum in pldm_msgbuf_extract_sensor_value() 1824. pdr: Remove redundant constant for minimum numeric sensor PDR length 1835. tests: oem: meta: Fix fileio use of msgbuf 184 185## [0.7.0] - 2023-08-29 186 187### Added 188 1891. state-set: Add new enum for Operational Fault Status enum 190 191### Changed 192 1931. transport: Match specified metadata in pldm_transport_send_recv_msg() 1942. transport: mctp-demux: Drop ABI annotation for internal symbols 1953. transport: Stabilise core transport and implementation APIs 196 197 This stabilisation covers the following headers and functions: 198 199 - libpldm/transport.h 200 201 - pldm_transport_poll() 202 - pldm_transport_send_msg() 203 - pldm_transport_recv_msg() 204 - pldm_transport_send_recv_msg() 205 206 - libpldm/transport/af-mctp.h 207 208 - pldm_transport_af_mctp_init() 209 - pldm_transport_af_mctp_destroy() 210 - pldm_transport_af_mctp_core() 211 - pldm_transport_af_mctp_init_pollfd() 212 - pldm_transport_af_mctp_map_tid() 213 - pldm_transport_af_mctp_unmap_tid() 214 215 - libpldm/transport/mctp-demux.h 216 - pldm_transport_mctp_demux_init() 217 - pldm_transport_mctp_demux_destroy() 218 - pldm_transport_mctp_demux_core() 219 - pldm_transport_mctp_demux_init_pollfd() 220 - pldm_transport_mctp_demux_map_tid() 221 - pldm_transport_mctp_demux_unmap_tid() 222 223### Deprecated 224 2251. All the existing "requester" APIs from `libpldm/pldm.h` (also known as 226 `libpldm/requester/pldm.h`): 227 228 - pldm_open() 229 - pldm_send_recv() 230 - pldm_send() 231 - pldm_recv() 232 - pldm_recv_any() 233 - pldm_close() 234 235 Users should migrate to the newer "transport" APIs instead. 236 237## Fixed 238 2391. tests: Exclude transport tests when build excludes testing ABIs 2402. abi: Capture deprecation of pldm_close() 241 242## [0.6.0] - 2023-08-22 243 244### Changed 245 2461. pdr: Avoid ID overflow in pldm_entity_association_tree_add_entity() 2472. meson: Apply `b_ndebug=if-release` by default 2483. pdr : Stabilize pldm_entity_association_tree_add_entity() 2494. pdr: Stabilise pldm_entity_association_tree_find_with_locality() 2505. pdr: Stabilize pldm_entity_node_get_remote_container_id() 2516. transport: af-mctp: Assign out-params on success in \*\_recv() 2527. transport: Generalise the pldm_transport_recv_msg() API 253 254### Removed 255 2561. pdr: Remove pldm_entity_association_pdr_add() 2572. state-set: Remove enum pldm_state_set_operational_fault_status_values 258 259### Fixed 260 2611. transport: register init_pollfd callback for af-mctp 2622. transport: fix init_pollfd function parameter 2633. transport: Fix doxygen and variables for send and recv functions 2644. transport: af-mctp: Ensure malloc() succeeds in \*\_recv() 265 266## [0.5.0] - 2023-08-09 267 268### Added 269 2701. pdr: Introduce pldm_entity_association_pdr_add_check() 271 272### Changed 273 2741. pdr: Allow record_handle to be NULL for pldm_pdr_add_check() 2752. transport: pldm_transport_poll(): Adjust return value semantics 2763. transport: free un-wanted responses in pldm_transport_send_recv_msg() 277 278### Deprecated 279 2801. state-set: Enum pldm_state_set_operational_fault_status_values 281 282 The enum operational_fault_status is defined with wrong members and will 283 eventually be replaced with the correct members. Any uses of 284 pldm_state_set_operational_fault_status_values members should move to 285 equivalent pldm_state_set_operational_stress_status_values members if needed. 286 2872. platform: Struct field name in fru_record_set PDR 288 289 References to entity_instance_num should be changed to entity_instance 290 2913. platform: Struct field name in numeric sensor value PDR 292 293 References to entity_instance_num should be changed to entity_instance 294 295### Removed 296 2971. bios_table: Remove pldm_bios_table_attr_entry_integer_encode_length() 2982. bios_table: Remove pldm_bios_table_attr_value_entry_encode_enum() 2993. bios_table: Remove pldm_bios_table_attr_value_entry_encode_string() 3004. bios_table: Remove pldm_bios_table_attr_value_entry_encode_integer() 3015. bios_table: Remove pldm_bios_table_append_pad_checksum() 3026. fru: Remove get_fru_record_by_option() 3037. pdr: Make is_present() static 3048. pdr: Remove pldm_pdr_add() 3059. pdr: Remove pldm_pdr_add_fru_record_set() 30610. pdr: Remove pldm_entity_association_pdr_add_from_node() 30711. pdr: Make find_entity_ref_in_tree() static 30812. pdr: Make entity_association_tree_find() static 309 310### Fixed 311 3121. requester: Fix response buffer cast in pldm_send_recv() 3132. pdr: Hoist record handle overflow test to avoid memory leak 3143. transport: Correct comparison in while loop condition 315 316## [0.4.0] - 2023-07-14 317 318### Added 319 3201. bios_table: Introduce pldm_bios_table_append_pad_checksum_check() 3212. fru: Introduce get_fru_record_by_option_check() 3223. pdr: Introduce pldm_entity_association_pdr_add_from_node_check() 3234. pdr: Introduce pldm_pdr_add_check() 3245. pdr: Introduce pldm_pdr_add_fru_record_set_check() 325 326### Changed 327 3281. requester: Mark pldm_close() as LIBPLDM_ABI_TESTING 3292. requester: Expose pldm_close() in header 3303. bios_table: pldm_bios_table_string_entry_encode_check(): Handle overflow 3314. bios_table: pldm_bios_table_iter_create(): Return NULL on failed alloc 3325. bios_table: pldm_bios_table_iter_next(): Invalid entry halts iteration 3336. pdr: pldm_pdr_init(): Return NULL on allocation failure 3347. pdr: pldm_pdr_destroy(): Exit early if repo is NULL 3358. pdr: Document preconditions for trivial accessor functions 336 337 A trivial accessor function is one that exposes properties of an object in a 338 way can't result in an error, beyond passing an invalid argument to the 339 function. For APIs meeting this definition we define a precondition that 340 struct pointers must point to valid objects to avoid polluting the function 341 prototypes. The following APIs now have this precondition explicitly defined: 342 343 - pldm_entity_extract() 344 - pldm_entity_get_parent() 345 - pldm_entity_is_exist_parent() 346 - pldm_entity_is_node_parent() 347 - pldm_is_current_parent_child 348 - pldm_is_empty_entity_assoc_tree() 349 - pldm_pdr_get_record_count() 350 - pldm_pdr_get_record_handle() 351 - pldm_pdr_get_repo_size() 352 - pldm_pdr_record_is_remote() 353 3549. pdr: pldm_entity_node_get_remote_container_id() is a trivial accessor 35510. pdr: pldm_pdr_fru_record_set_find_by_rsi(): Exit early on NULL arguments 35611. pdr: pldm_entity_association_tree_init(): Return NULL on failed alloc 35712. pdr: pldm_entity_association_tree_visit(): Document preconditions 35813. pdr: pldm_entity_association_tree_visit(): Exit early on failure 35914. pdr: pldm_entity_association_tree_destroy(): Exit early on bad argument 36015. pdr: pldm_entity_get_num_children(): Return zero for invalid arguments 36116. pdr: pldm_is_current_parent_child(): Return false for invalid arguments 36217. pdr: pldm_entity_association_pdr_add(): Exit early on bad arguments 36318. pdr: pldm_find_entity_ref_in_tree(): Exit early on bad arguments 36419. pdr: pldm_entity_association_tree_find(): Early exit on bad arguments 36520. pdr: pldm_entity_association_tree_destroy_root(): Exit early on bad arg 36621. pdr: pldm_entity_association_pdr_extract(): Early exit on bad arguments 36722. pdr: pldm_entity_association_pdr_extract(): Assign out params at exit 36823. pdr: pldm_entity_get_num_children(): Don't return invalid values 36924. libpldm: Lift or remove asserts where a subsequent check exists 370 371### Deprecated 372 3731. pldm_bios_table_attr_entry_integer_encode() 374 375 Migrate to pldm_bios_table_attr_entry_integer_encode_check() 376 3772. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_enum() 378 379 Migrate to pldm_bios_table_attr_value_entry_encode_enum_check() 380 3813. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_string() 382 383 Migrate to pldm_bios_table_attr_value_entry_encode_string_check() 384 3854. bios_table: Deprecate pldm_bios_table_attr_value_entry_encode_integer() 386 387 Migrate to pldm_bios_table_attr_value_entry_encode_integer_check() 388 3895. pdr: Deprecate is_present() 390 391 There should be no users of this symbol. If you are a user, you should figure 392 out how to stop, or get in touch. This symbol will be marked static the 393 release after deprecation. 394 3956. pdr: Deprecate find_entity_ref_in_tree() 396 397 There should be no users of this symbol. If you are a user, you should figure 398 out how to stop, or get in touch. This symbol will be marked static the 399 release after deprecation. 400 4017. pdr: Deprecate entity_association_tree_find() 402 403 There should be no users of this symbol. If you are a user, you should figure 404 out how to stop, or get in touch. This symbol will be marked static the 405 release after deprecation. 406 4078. bios_table: Stabilise pldm_bios_table_append_pad_checksum_check() 408 409 pldm_bios_table_append_pad_checksum() is deprecated by this change. Users of 410 pldm_bios_table_append_pad_checksum() should migrate to 411 pldm_bios_table_append_pad_checksum_check() 412 4139. fru: Stabilise get_fru_record_by_option_check() 414 415 get_fru_record_by_option() is deprecated by this change. Users of 416 get_fru_record_by_option() should migrate to get_fru_record_by_option_check() 417 41810. pdr: Stabilise pldm_entity_association_pdr_add_from_node_check() 419 420 pldm_entity_association_pdr_add_from_node() is deprecated by this change. 421 Users of pldm_entity_association_pdr_add_from_node() should migrate to 422 pldm_entity_association_pdr_add_from_node_check() 423 42411. pdr: Stabilise pldm_pdr_add_check() 425 426 pldm_pdr_add() is deprecated by this change. Users of pldm_pdr_add() should 427 migrate to pldm_pdr_add_check() 428 42912. pdr: Stabilise pldm_pdr_add_fru_record_set_check() 430 431 pldm_pdr_add_fru_record_set() is deprecated by this change. Users of 432 pldm_pdr_add_fru_record_set() should migrate to 433 pldm_pdr_add_fru_record_set_check() 434 435### Removed 436 4371. bios_table: Remove deprecated APIs sanitized by assert(): 438 439 - pldm_bios_table_string_entry_encode() 440 - pldm_bios_table_string_entry_decode_string() 441 - pldm_bios_table_attr_entry_enum_encode() 442 - pldm_bios_table_attr_entry_enum_decode_pv_num() 443 - pldm_bios_table_attr_entry_enum_decode_def_num() 444 - pldm_bios_table_attr_entry_enum_decode_pv_hdls() 445 - pldm_bios_table_attr_entry_string_encode() 446 - pldm_bios_table_attr_entry_string_decode_def_string_length() 447 448### Fixed 449 4501. pdr: Return success for pldm_pdr_find_child_container_id_range_exclude() API 4512. pdr: Rework pldm_pdr_find_container_id_range_exclude() API 4523. transport: mctp-demux: Don't test socket for non-zero value 4534. requester: Return PLDM_REQUESTER_OPEN_FAIL from pldm_open() on error 4545. pdr: pldm_pdr_fru_record_set_find_by_rsi(): Document reality of return 4556. transport: Fix possible NULL ptr deref in pldm_socket_sndbuf_init() 4567. abi: Update to remove pldm_close() from reference dumps 4578. bios_table: Annotate pldm_bios_table_attr_value_entry_encode_integer() 458 459## [0.3.0] - 2023-06-23 460 461### Added 462 4631. Add encode/decode pldmMessagePollEvent data 4642. README: Add a section on working with libpldm 4653. pdr: Introduce remote_container_id and associated APIs 4664. pdr: Add APIs for creating and locating remote PDRs 4675. pdr: Add pldm_pdr_find_last_in_range() 4686. pdr: Add pldm_entity_association_pdr_add_from_node_with_record_handle() 4697. pdr: Add pldm_pdr_find_container_id_range_exclude() 470 471### Changed 472 4731. include: Move installed transport.h under libpldm/ 4742. libpldm: Explicit deprecated, stable and testing ABI classes 4753. meson: Reduce strength of oem-ibm requirements from enabled to allowed 476 477 The `oem-ibm` feature is now enabled by the default meson configuration, for 478 CI purposes. `oem-ibm` is still disabled by default in the `libpldm` bitbake 479 recipe: 480 481 <https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/libpldm/libpldm_git.bb#L10> 482 483 To disable `oem-ibm` in your development builds, pass `-Doem-ibm=disabled` 484 when invoking `meson setup` 485 4864. bios_table: Relax pldm_bios_table_string_entry_decode_string_check() 4875. bios_table: Relax pldm_bios_table_attr_entry_enum_decode_pv_hdls_check() 488 489### Deprecated 490 4911. bios_table: Deprecate APIs with arguments sanitized using assert() 492 493 C provides enough foot-guns without us encoding them into library APIs. 494 Specifically, deprecate the following in favour of their `*_check()` variants 495 which ensure assertions won't fail or otherwise invoke UB: 496 497 - pldm_bios_table_string_entry_encode() 498 - pldm_bios_table_string_entry_decode_string() 499 - pldm_bios_table_attr_entry_enum_encode() 500 - pldm_bios_table_attr_entry_enum_decode_pv_num() 501 - pldm_bios_table_attr_entry_enum_decode_def_num() 502 - pldm_bios_table_attr_entry_enum_decode_pv_hdls() 503 - pldm_bios_table_attr_entry_string_encode() 504 - pldm_bios_table_attr_entry_string_decode_def_string_length() 505 506### Removed 507 5081. libpldm: Remove the requester-api option 509 510### Fixed 511 5121. requester: Make pldm_open() return existing fd 5132. transport: Prevent sticking in waiting for response 5143. transport: Match on response in pldm_transport_send_recv_msg() 5154. requester: Add check before accessing hdr in pldm_recv() 5165. bios_table: pldm_bios_table_attr_entry_string_info_check() NULL deref 517