commit	2613c2785d5cd5e4c007d1bca8bb414079c85ffb	[log] [tgz]
author	Andrew Jeffery <andrew@codeconstruct.com.au>	Wed Mar 12 14:15:41 2025 +1030
committer	Andrew Jeffery <andrew@codeconstruct.com.au>	Sat Jun 14 12:40:20 2025 +0930
tree	a4f3e2c059d9bd87c1925c65ffe71339100e22f8
parent	bacbbac1ddc5ee4b4184b73bccdd535b05f9e870 [diff]

dsp: firmware_update: Introduce iterators for parsing firmware packages

The new collection of APIs allows parsing of arbitrary PLDM firmware
update packages in a style that is reasonably ergonomic and free of
library allocations.

As a rough sketch, use of the API looks as follows:

```
/* Pin the package parsing to format revision 2 */
DEFINE_PLDM_PACKAGE_FORMAT_PIN_FR02H(pin);

struct pldm_package_downstream_device_id_record ddrec;
struct pldm_package_component_image_information info;
struct pldm_package_firmware_device_id_record fdrec;
pldm_package_header_information_pad hdr;
struct pldm_package_iter iter;
int rc;

...

rc = decode_pldm_firmware_update_package(package, in, &pin, &hdr, &iter);
if (rc < 0) { ... }

/* Do something with hdr */

foreach_pldm_package_firmware_device_id_record(iter, fdrec, rc)
{
	struct pldm_descriptor desc;

	/* Do something with fdrec */

	foreach_pldm_package_firmware_device_id_record_descriptor(iter, fdrec,
								  desc, rc)
	{
		/* Do something with desc */
	}
	if (rc) { /* Handle desc decode failure */ }
}
if (rc) { /* Handle fdrec decode failure */ }

foreach_pldm_package_downstream_device_id_record(iter, ddrec, rc)
{
	struct pldm_descriptor desc;

	/* Do something with ddrec */

	foreach_pldm_package_downstream_device_id_record_descriptor(iter, ddrec,
								    desc, rc)
	{
		/* Do something with desc */
	}
	if (rc) { /* Handle desc decode failure */ }
}
if (rc) { /* Handle ddrec decode failure */ }

foreach_pldm_package_component_image_information(iter, info, rc)
{
	/* Do something with info */
}
if (rc) { /* Handle info decode failure */ }
```

Note that these new APIs intersects with some existing functionality.
Where possible, implementations have been unified, however, the existing
APIs were inflexible and unergonomic, requiring pointer arithmetic on
the part of the caller, and could not safely cater to concepts added in
later revisions of the spec. The existing APIs will be deprecated in a
later patch.

Further to that, the implementation of the component image information
parsing could not be unified in a way that wasn't awkward. The existing
API passed raw image offsets back to the caller, where the new API
resolves the offsets against the image location in memory, yielding a
valid pointer and bounds-checked length (thereby relieving the caller of
the pointer arithmetic). Unwinding that back to a raw offset seems
tedious at best in the context of other tests for pointer validity, so
don't even try.

Change-Id: I53472ca22b4c8aa79a5515b20a72bf8f66ed66e3
Co-developed-by: Rajeev Ranjan <rajeeranjan@nvidia.com>
Signed-off-by: Andrew Jeffery <andrew@codeconstruct.com.au>

6 files changed

tree: a4f3e2c059d9bd87c1925c65ffe71339100e22f8

README.md

libpldm

This is a library which deals with the encoding and decoding of PLDM messages. It should be possible to use this library by projects other than OpenBMC, and hence certain constraints apply to it:

keeping it light weight
implementation in C
minimal dynamic memory allocations
endian-safe
no OpenBMC specific dependencies

Source files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c], etc.

Given a PLDM command "foo", the library will provide the following API: For the Requester function:

encode_foo_req() - encode a foo request
decode_foo_resp() - decode a response to foo

For the Responder function:

decode_foo_req() - decode a foo request
encode_foo_resp() - encode a response to foo

The library also provides API to pack and unpack PLDM headers.

To Build

libpldm is configured and built using meson. Python's pip or pipx can be used to install a recent version on your machine:

pipx install meson

Once meson is installed:

meson setup build && meson compile -C build

To run unit tests

meson test -C build

Working with `libpldm`

Components of the library ABI[^1] (loosely, functions) are separated into three categories:

[^1]: "library API + compiler ABI = library ABI"

Stable
Testing
Deprecated

Applications depending on libpldm should aim to only use functions from the stable category. However, this may not always be possible. What to do when required functions fall into the deprecated or testing categories is outlined below.

What does it mean to mark a function as stable?

Marking a function as stable makes the following promise to users of the library:

We will not remove or change the symbol name, argument count, argument types, return type, or interpretation of relevant values for the function before first marking it as LIBPLDM_ABI_DEPRECATED and then subsequently creating a tagged release

Marking a function as stable does not promise that it is free of implementation bugs. It is just a promise that the prototype won't change without notice.

Given this, it is always okay to implement functions marked stable in terms of functions marked testing inside of libpldm. If we remove or change the prototype of a function marked testing the only impact is that we need to fix up any call sites of that function in the same patch.

The ABI lifecycle

---
title: libpldm symbol lifecycle
---
stateDiagram-v2
    direction LR
    [*] --> Testing: Add
    Testing --> Testing: Change
    Testing --> [*]: Remove
    Testing --> Stable: Stabilise
    Stable --> Deprecated: Deprecate
    Deprecated --> [*]: Remove

The ABI of the library produced by the build is controlled using the abi meson option. The following use cases determine how the abi option should be specified:

Use Case	Meson Configuration
Production	`-Dabi=deprecated,stable`
Maintenance	`-Dabi=stable`
Development	`-Dabi=deprecated,stable,testing`

Maintenance

Applications and libraries that depend on libpldm can identify how to migrate off of deprecated APIs by constraining the library ABI to the stable category. This will force the compiler identify any call-sites that try to link against deprecated symbols.

Development

Applications and libraries often require functionality that doesn't yet exist in libpldm. The work is thus in two parts:

Add the required APIs to libpldm
Use the new APIs from libpldm in the dependent application or library

Adding APIs to a library is a difficult task. Generally, once an API is exposed in the library's ABI, any changes to the API risk breaking applications already making use of it. To make sure we have more than one shot at getting an API right, all new APIs must first be exposed in the testing category. Concretely:

Patches adding new APIs MUST mark them as testing and MUST NOT mark them as stable.

Marking functions as testing, stable or deprecated

Three macros are provided through config.h (automatically included for all translation units) to mark functions as testing, stable or deprecated:

LIBPLDM_ABI_TESTING
LIBPLDM_ABI_STABLE
LIBPLDM_ABI_DEPRECATED

These annotations go immediately before your function signature:

LIBPLDM_ABI_TESTING
pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport,
                                            pldm_tid_t tid,
                                            const void *pldm_req_msg,
                                            size_t req_msg_len)
{
    ...
}

Requirements for stabilising a function

As mentioned above, all new functions must first be added in the testing category (using the LIBPLDM_ABI_TESTING annotation).

To move a function from the testing category to the stable category, its required that patches demonstrating use of the function in a dependent application or library be linked in the commit message of the stabilisation change. We require this to demonstrate that the implementer has considered its use in context before preventing us from making changes to the API.

Building a dependent application or library against a testing ABI

Meson is broadly used in the OpenBMC ecosystem, the historical home of libpldm. Meson's subprojects are a relatively painless way of managing dependencies for the purpose of developing complex applications and libraries. Use of libpldm as a subproject is both supported and encouraged.

libpldm's ABI can be controlled from a parent project through meson's subproject configuration syntax:

meson setup ... -Dlibpldm:abi=deprecated,stable,testing ...

OEM/vendor-specific functions

libpldm accepts support for OEM or vendor-specific extensions. To add support for an OEM's extensions:

Document the wire format for all OEM messages under docs/oem/${OEM_NAME}/
Add public OEM API declarations and definitions under include/libpldm/oem/${OEM_NAME}/, and install them to the same relative location.
Implement the public OEM APIs under src/oem/${OEM_NAME}/
Implement the OEM API tests under tests/oem/${OEM_NAME}/

The ${OEM_NAME} folder must be created with the name of the OEM/vendor in lower case.

Finally, the OEM name must be added to the list of choices for the oem meson option, and the meson.build files updated throughout the tree to guard integration of the OEM extensions.