| commit | a189696768c2aea88202c4e9530d76a69bd1947e | [log] [tgz] |
|---|---|---|
| author | Andrew Jeffery <andrew@codeconstruct.com.au> | Mon Mar 03 21:41:25 2025 +1030 |
| committer | Andrew Jeffery <andrew@codeconstruct.com.au> | Tue Mar 25 17:03:33 2025 +1030 |
| tree | e270fcf81b506c31c2650893930b0311e3a903d1 | |
| parent | 63b5a66f9611df69b192b7bd21f339320814bff0 [diff] |
msgbuf: Rework error handling to improve soundness
Design the implementation to uphold the invariant that a non-negative
remaining value implies the cursor pointer is valid, and that under
other conditions error values must be observed by the msgbuf user. The
former is tested with assertions in the implementation. The latter is
enforced by construction.
With this change, all msgbuf instances for which
pldm_msgbuf_init_errno() succeeds must be either completed or discarded
by calls to the pldm_msgbuf_complete*() or pldm_msgbuf_discard() APIs
respectively.
We then build on the properties that:
- pldm_msgbuf_init_errno() is marked with the warn_unused_result
function attribute
- pldm_msgbuf_init_errno() returns errors for invalid buffer
configurations
- The complete and discard APIs are marked with the warn_unused_result
function attribute
- The complete APIs test for negative remaining values and return an
error if encountered.
- The discard API propagates the provided error code
Together these provide the foundation to ensure that buffer access
errors are (eventually) detected.
A msgbuf object is always in one of the uninitialized, valid, invalid,
or completed states. The states are defined as follows:
- Uninitialized: Undefined values for remaining and cursor
- Valid: cursor points to a valid object, remaining is both non-negative
and describes a range contained within the object pointed to
by cursor
- Invalid: The value of remaining is negative. The value of cursor is
unspecified.
- Completed: the value of remaining is INTMAX_MIN and cursor is NULL
msgbuf instances must always be in the completed state by the time
their storage is reclaimed. To enforce this, PLDM_MSGBUF_DEFINE_P()
is introduced both to simplify definition of related variables, and
to exploit the compiler's 'cleanup' attribute. The cleanup function
associated with the msgbuf object asserts that the referenced object is
in the completed state.
From there, update the implementations of the msgbuf APIs such that
exceeding implementation type limits forces the msgbuf object to the
invalid state (in addition to returning an error value) to relieve the
caller from testing the result of all API invocations.
Change-Id: I4d78ddc5f567d4148f2f6d8f3e7570e97c316bbb
Signed-off-by: Andrew Jeffery <andrew@codeconstruct.com.au>
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:
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.
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
meson test -C build
libpldmComponents of the library ABI[^1] (loosely, functions) are separated into three categories:
[^1]: "library API + compiler ABI = library ABI"
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.
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_DEPRECATEDand 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.
--- 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 |
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.
Applications and libraries often require functionality that doesn't yet exist in libpldm. The work is thus in two parts:
libpldmlibpldm in the dependent application or libraryAdding 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.
Three macros are provided through config.h (automatically included for all translation units) to mark functions as testing, stable or deprecated:
LIBPLDM_ABI_TESTINGLIBPLDM_ABI_STABLELIBPLDM_ABI_DEPRECATEDThese 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) { ... }
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.
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 ...
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.