Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
abi/x86_64/ | H | - | - | 13,892 | 13,891 | |
docs/ | H | - | - | 532 | 350 | |
evolutions/v0.9.1/ | H | - | - | 84 | 60 | |
include/ | H | - | - | 10,903 | 4,365 | |
instance-db/ | H | - | - | |||
scripts/ | H | - | - | 200 | 108 | |
src/ | H | - | - | 18,936 | 15,204 | |
subprojects/ | H | - | - | 4 | 3 | |
tests/ | H | - | - | 23,289 | 18,745 | |
.clang-format | H A D | 20-Oct-2023 | 3.6 KiB | 119 | 116 | |
.clang-tidy | H A D | 09-Sep-2024 | 7.3 KiB | 219 | 217 | |
CHANGELOG.md | H A D | 03-Mar-2025 | 27.7 KiB | 767 | 549 | |
Doxyfile.in | H A D | 04-Mar-2025 | 12.2 KiB | |||
LICENSE | H A D | 10-Oct-2022 | 11.1 KiB | 202 | 169 | |
OWNERS | H A D | 12-Mar-2024 | 1.9 KiB | 57 | 52 | |
README.md | H A D | 02-Feb-2025 | 6.6 KiB | 211 | 152 | |
meson.build | H A D | 04-Mar-2025 | 3 KiB | 86 | 72 | |
meson.options | H A D | 01-Feb-2025 | 606 | 26 | 25 |
README.md
1# libpldm 2 3This is a library which deals with the encoding and decoding of PLDM messages. 4It should be possible to use this library by projects other than OpenBMC, and 5hence certain constraints apply to it: 6 7- keeping it light weight 8- implementation in C 9- minimal dynamic memory allocations 10- endian-safe 11- no OpenBMC specific dependencies 12 13Source files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c], 14etc. 15 16Given a PLDM command "foo", the library will provide the following API: For the 17Requester function: 18 19```c 20encode_foo_req() - encode a foo request 21decode_foo_resp() - decode a response to foo 22``` 23 24For the Responder function: 25 26```c 27decode_foo_req() - decode a foo request 28encode_foo_resp() - encode a response to foo 29``` 30 31The library also provides API to pack and unpack PLDM headers. 32 33## To Build 34 35`libpldm` is configured and built using `meson`. Python's `pip` or 36[`pipx`][pipx] can be used to install a recent version on your machine: 37 38[pipx]: https://pipx.pypa.io/latest/ 39 40```sh 41pipx install meson 42``` 43 44Once `meson` is installed: 45 46```sh 47meson setup build && meson compile -C build 48``` 49 50## To run unit tests 51 52```sh 53meson test -C build 54``` 55 56## Working with `libpldm` 57 58Components of the library ABI[^1] (loosely, functions) are separated into three 59categories: 60 61[^1]: ["library API + compiler ABI = library ABI"][libstdc++-library-abi] 62 63[libstdc++-library-abi]: 64 https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html 65 661. Stable 672. Testing 683. Deprecated 69 70Applications depending on `libpldm` should aim to only use functions from the 71stable category. However, this may not always be possible. What to do when 72required functions fall into the deprecated or testing categories is outlined 73below. 74 75### What does it mean to mark a function as stable? 76 77Marking a function as stable makes the following promise to users of the 78library: 79 80> We will not remove or change the symbol name, argument count, argument types, 81> return type, or interpretation of relevant values for the function before 82> first marking it as `LIBPLDM_ABI_DEPRECATED` and then subsequently creating a 83> tagged release 84 85Marking a function as stable does _not_ promise that it is free of 86implementation bugs. It is just a promise that the prototype won't change 87without notice. 88 89Given this, it is always okay to implement functions marked stable in terms of 90functions marked testing inside of libpldm. If we remove or change the prototype 91of a function marked testing the only impact is that we need to fix up any call 92sites of that function in the same patch. 93 94### The ABI lifecycle 95 96```mermaid 97--- 98title: libpldm symbol lifecycle 99--- 100stateDiagram-v2 101 direction LR 102 [*] --> Testing: Add 103 Testing --> Testing: Change 104 Testing --> [*]: Remove 105 Testing --> Stable: Stabilise 106 Stable --> Deprecated: Deprecate 107 Deprecated --> [*]: Remove 108``` 109 110The ABI of the library produced by the build is controlled using the `abi` meson 111option. The following use cases determine how the `abi` option should be 112specified: 113 114| Use Case | Meson Configuration | 115| ----------- | --------------------------------- | 116| Production | `-Dabi=deprecated,stable` | 117| Maintenance | `-Dabi=stable` | 118| Development | `-Dabi=deprecated,stable,testing` | 119 120### Maintenance 121 122Applications and libraries that depend on `libpldm` can identify how to migrate 123off of deprecated APIs by constraining the library ABI to the stable category. 124This will force the compiler identify any call-sites that try to link against 125deprecated symbols. 126 127### Development 128 129Applications and libraries often require functionality that doesn't yet exist in 130`libpldm`. The work is thus in two parts: 131 1321. Add the required APIs to `libpldm` 1332. Use the new APIs from `libpldm` in the dependent application or library 134 135Adding APIs to a library is a difficult task. Generally, once an API is exposed 136in the library's ABI, any changes to the API risk breaking applications already 137making use of it. To make sure we have more than one shot at getting an API 138right, all new APIs must first be exposed in the testing category. Concretely: 139 140Patches adding new APIs MUST mark them as testing and MUST NOT mark them as 141stable. 142 143### Marking functions as testing, stable or deprecated 144 145Three macros are provided through `config.h` (automatically included for all 146translation units) to mark functions as testing, stable or deprecated: 147 1481. `LIBPLDM_ABI_TESTING` 1492. `LIBPLDM_ABI_STABLE` 1503. `LIBPLDM_ABI_DEPRECATED` 151 152These annotations go immediately before your function signature: 153 154```c 155LIBPLDM_ABI_TESTING 156pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport, 157 pldm_tid_t tid, 158 const void *pldm_req_msg, 159 size_t req_msg_len) 160{ 161 ... 162} 163``` 164 165### Requirements for stabilising a function 166 167As mentioned above, all new functions must first be added in the testing 168category (using the `LIBPLDM_ABI_TESTING` annotation). 169 170To move a function from the testing category to the stable category, its 171required that patches demonstrating use of the function in a dependent 172application or library be linked in the commit message of the stabilisation 173change. We require this to demonstrate that the implementer has considered its 174use in context _before_ preventing us from making changes to the API. 175 176### Building a dependent application or library against a testing ABI 177 178Meson is broadly used in the OpenBMC ecosystem, the historical home of 179`libpldm`. Meson's subprojects are a relatively painless way of managing 180dependencies for the purpose of developing complex applications and libraries. 181Use of `libpldm` as a subproject is both supported and encouraged. 182 183`libpldm`'s ABI can be controlled from a parent project through meson's 184subproject configuration syntax: 185 186```shell 187meson setup ... -Dlibpldm:abi=deprecated,stable,testing ... 188``` 189 190## OEM/vendor-specific functions 191 192libpldm accepts support for OEM or vendor-specific extensions. To add support 193for an OEM's extensions: 194 1951. Document the wire format for all OEM messages under `docs/oem/${OEM_NAME}/` 196 1972. Add public OEM API declarations and definitions under 198 `include/libpldm/oem/${OEM_NAME}/`, and install them to the same relative 199 location. 200 2013. Implement the public OEM APIs under `src/oem/${OEM_NAME}/` 202 2034. Implement the OEM API tests under `tests/oem/${OEM_NAME}/` 204 205The `${OEM_NAME}` folder must be created with the name of the OEM/vendor in 206lower case. 207 208Finally, the OEM name must be added to the list of choices for the `oem` meson 209option, and the `meson.build` files updated throughout the tree to guard 210integration of the OEM extensions. 211