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 35Need `meson` and `ninja`. Alternatively, source an OpenBMC ARM/x86 SDK. 36 37```sh 38meson setup builddir && ninja -C builddir 39``` 40 41## To run unit tests 42 43The simplest way of running the tests is as described by the meson man page: 44 45```sh 46meson setup builddir && meson test -C builddir 47``` 48 49## Working with `libpldm` 50 51Components of the library ABI[^1] (loosely, functions) are separated into three 52categories: 53 54[^1]: ["library API + compiler ABI = library ABI"][libstdc++-library-abi] 55 56[libstdc++-library-abi]: 57 https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html 58 591. Stable 602. Testing 613. Deprecated 62 63Applications depending on `libpldm` should aim to only use functions from the 64stable category. However, this may not always be possible. What to do when 65required functions fall into the deprecated or testing categories is outlined 66below. 67 68### What does it mean to mark a function as stable? 69 70Marking a function as stable makes the following promise to users of the 71library: 72 73> We will not remove or change the symbol name, argument count, argument types, 74> return type, or interpretation of relevant values for the function before 75> first marking it as `LIBPLDM_ABI_DEPRECATED` and then subsequently creating a 76> tagged release 77 78Marking a function as stable does _not_ promise that it is free of 79implementation bugs. It is just a promise that the prototype won't change 80without notice. 81 82Given this, it is always okay to implement functions marked stable in terms of 83functions marked testing inside of libpldm. If we remove or change the prototype 84of a function marked testing the only impact is that we need to fix up any call 85sites of that function in the same patch. 86 87### The ABI lifecycle 88 89```mermaid 90--- 91title: libpldm symbol lifecycle 92--- 93stateDiagram-v2 94 direction LR 95 [*] --> Testing: Add 96 Testing --> Testing: Change 97 Testing --> [*]: Remove 98 Testing --> Stable: Stabilise 99 Stable --> Deprecated: Deprecate 100 Deprecated --> [*]: Remove 101``` 102 103The ABI of the library produced by the build is controlled using the `abi` meson 104option. The following use cases determine how the `abi` option should be 105specified: 106 107| Use Case | Meson Configuration | 108| ----------- | --------------------------------- | 109| Production | `-Dabi=deprecated,stable` | 110| Maintenance | `-Dabi=stable` | 111| Development | `-Dabi=deprecated,stable,testing` | 112 113### Maintenance 114 115Applications and libraries that depend on `libpldm` can identify how to migrate 116off of deprecated APIs by constraining the library ABI to the stable category. 117This will force the compiler identify any call-sites that try to link against 118deprecated symbols. 119 120### Development 121 122Applications and libraries often require functionality that doesn't yet exist in 123`libpldm`. The work is thus in two parts: 124 1251. Add the required APIs to `libpldm` 1262. Use the new APIs from `libpldm` in the dependent application or library 127 128Adding APIs to a library is a difficult task. Generally, once an API is exposed 129in the library's ABI, any changes to the API risk breaking applications already 130making use of it. To make sure we have more than one shot at getting an API 131right, all new APIs must first be exposed in the testing category. Concretely: 132 133Patches adding new APIs MUST mark them as testing and MUST NOT mark them as 134stable. 135 136### Marking functions as testing, stable or deprecated 137 138Three macros are provided through `config.h` (automatically included for all 139translation units) to mark functions as testing, stable or deprecated: 140 1411. `LIBPLDM_ABI_TESTING` 1422. `LIBPLDM_ABI_STABLE` 1433. `LIBPLDM_ABI_DEPRECATED` 144 145These annotations go immediately before your function signature: 146 147```c 148LIBPLDM_ABI_TESTING 149pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport, 150 pldm_tid_t tid, 151 const void *pldm_req_msg, 152 size_t req_msg_len) 153{ 154 ... 155} 156``` 157 158### Requirements for stabilising a function 159 160As mentioned above, all new functions must first be added in the testing 161category (using the `LIBPLDM_ABI_TESTING` annotation). 162 163To move a function from the testing category to the stable category, its 164required that patches demonstrating use of the function in a dependent 165application or library be linked in the commit message of the stabilisation 166change. We require this to demonstrate that the implementer has considered its 167use in context _before_ preventing us from making changes to the API. 168 169### Building a dependent application or library against a testing ABI 170 171Meson is broadly used in the OpenBMC ecosystem, the historical home of 172`libpldm`. Meson's subprojects are a relatively painless way of managing 173dependencies for the purpose of developing complex applications and libraries. 174Use of `libpldm` as a subproject is both supported and encouraged. 175 176`libpldm`'s ABI can be controlled from a parent project through meson's 177subproject configuration syntax: 178 179```shell 180meson setup ... -Dlibpldm:abi=deprecated,stable,testing ... 181``` 182 183## OEM/vendor-specific functions 184 185libpldm accepts support for OEM or vendor-specific extensions. To add support 186for an OEM's extensions: 187 1881. Document the wire format for all OEM messages under `docs/oem/${OEM_NAME}/` 189 1902. Add public OEM API declarations and definitions under 191 `include/libpldm/oem/${OEM_NAME}/`, and install them to the same relative 192 location. 193 1943. Implement the public OEM APIs under `src/oem/${OEM_NAME}/` 195 1964. Implement the OEM API tests under `tests/oem/${OEM_NAME}/` 197 198The `${OEM_NAME}` folder must be created with the name of the OEM/vendor in 199lower case. 200 201Finally, the OEM name must be added to the list of choices for the `oem` meson 202option, and the `meson.build` files updated throughout the tree to guard 203integration of the OEM extensions. 204