13896ecc7SManojkiran Eda# libpldm 2aa30d3efSPatrick Williams 33896ecc7SManojkiran EdaThis is a library which deals with the encoding and decoding of PLDM messages. 43896ecc7SManojkiran EdaIt should be possible to use this library by projects other than OpenBMC, and 53896ecc7SManojkiran Edahence certain constraints apply to it: 6aa30d3efSPatrick Williams 73896ecc7SManojkiran Eda- keeping it light weight 83896ecc7SManojkiran Eda- implementation in C 93896ecc7SManojkiran Eda- minimal dynamic memory allocations 103896ecc7SManojkiran Eda- endian-safe 113896ecc7SManojkiran Eda- no OpenBMC specific dependencies 123896ecc7SManojkiran Eda 133896ecc7SManojkiran EdaSource files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c], 143896ecc7SManojkiran Edaetc. 153896ecc7SManojkiran Eda 16aa30d3efSPatrick WilliamsGiven a PLDM command "foo", the library will provide the following API: For the 17aa30d3efSPatrick WilliamsRequester function: 18aa30d3efSPatrick Williams 19aa30d3efSPatrick Williams```c 203896ecc7SManojkiran Edaencode_foo_req() - encode a foo request 213896ecc7SManojkiran Edadecode_foo_resp() - decode a response to foo 223896ecc7SManojkiran Eda``` 23aa30d3efSPatrick Williams 243896ecc7SManojkiran EdaFor the Responder function: 25aa30d3efSPatrick Williams 26aa30d3efSPatrick Williams```c 273896ecc7SManojkiran Edadecode_foo_req() - decode a foo request 283896ecc7SManojkiran Edaencode_foo_resp() - encode a response to foo 293896ecc7SManojkiran Eda``` 30aa30d3efSPatrick Williams 313896ecc7SManojkiran EdaThe library also provides API to pack and unpack PLDM headers. 323896ecc7SManojkiran Eda 333896ecc7SManojkiran Eda## To Build 34aa30d3efSPatrick Williams 353896ecc7SManojkiran EdaNeed `meson` and `ninja`. Alternatively, source an OpenBMC ARM/x86 SDK. 36aa30d3efSPatrick Williams 37aa30d3efSPatrick Williams```sh 38aa30d3efSPatrick Williamsmeson setup builddir && ninja -C builddir 393896ecc7SManojkiran Eda``` 40aa30d3efSPatrick Williams 413896ecc7SManojkiran Eda## To run unit tests 42aa30d3efSPatrick Williams 433896ecc7SManojkiran EdaThe simplest way of running the tests is as described by the meson man page: 44aa30d3efSPatrick Williams 45aa30d3efSPatrick Williams```sh 46aa30d3efSPatrick Williamsmeson setup builddir && meson test -C builddir 473896ecc7SManojkiran Eda``` 48aa30d3efSPatrick Williams 4983841fb5SAndrew Jeffery## Working with `libpldm` 5083841fb5SAndrew Jeffery 51*1128d084SAndrew JefferyComponents of the library ABI[^1] (loosely, functions) are separated into three 52*1128d084SAndrew Jefferycategories: 53b220e27eSAndrew Jeffery 54b220e27eSAndrew Jeffery[^1]: ["library API + compiler ABI = library ABI"][libstdc++-library-abi] 55b220e27eSAndrew Jeffery 56b220e27eSAndrew Jeffery[libstdc++-library-abi]: 57b220e27eSAndrew Jeffery https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html 5883841fb5SAndrew Jeffery 5983841fb5SAndrew Jeffery1. Stable 6083841fb5SAndrew Jeffery2. Testing 6183841fb5SAndrew Jeffery3. Deprecated 6283841fb5SAndrew Jeffery 6383841fb5SAndrew JefferyApplications depending on `libpldm` should aim to only use functions from the 6483841fb5SAndrew Jefferystable category. However, this may not always be possible. What to do when 6583841fb5SAndrew Jefferyrequired functions fall into the deprecated or testing categories is outlined 6683841fb5SAndrew Jefferybelow. 6783841fb5SAndrew Jeffery 688cc5c776SAndrew Jeffery### What does it mean to mark a function as stable? 698cc5c776SAndrew Jeffery 708cc5c776SAndrew JefferyMarking a function as stable makes the following promise to users of the 718cc5c776SAndrew Jefferylibrary: 728cc5c776SAndrew Jeffery 738cc5c776SAndrew Jeffery> We will not remove or change the symbol name, argument count, argument types, 748cc5c776SAndrew Jeffery> return type, or interpretation of relevant values for the function before 758cc5c776SAndrew Jeffery> first marking it as `LIBPLDM_ABI_DEPRECATED` and then subsequently creating a 768cc5c776SAndrew Jeffery> tagged release 778cc5c776SAndrew Jeffery 788cc5c776SAndrew JefferyMarking a function as stable does _not_ promise that it is free of 798cc5c776SAndrew Jefferyimplementation bugs. It is just a promise that the prototype won't change 808cc5c776SAndrew Jefferywithout notice. 818cc5c776SAndrew Jeffery 828cc5c776SAndrew JefferyGiven this, it is always okay to implement functions marked stable in terms of 838cc5c776SAndrew Jefferyfunctions marked testing inside of libpldm. If we remove or change the prototype 848cc5c776SAndrew Jefferyof a function marked testing the only impact is that we need to fix up any call 858cc5c776SAndrew Jefferysites of that function in the same patch. 868cc5c776SAndrew Jeffery 8783841fb5SAndrew Jeffery### The ABI lifecycle 8883841fb5SAndrew Jeffery 8983841fb5SAndrew Jeffery```mermaid 9083841fb5SAndrew Jeffery--- 9183841fb5SAndrew Jefferytitle: libpldm symbol lifecycle 9283841fb5SAndrew Jeffery--- 9383841fb5SAndrew JefferystateDiagram-v2 9483841fb5SAndrew Jeffery direction LR 9583841fb5SAndrew Jeffery [*] --> Testing: Add 9683841fb5SAndrew Jeffery Testing --> Testing: Change 9783841fb5SAndrew Jeffery Testing --> [*]: Remove 9883841fb5SAndrew Jeffery Testing --> Stable: Stabilise 9983841fb5SAndrew Jeffery Stable --> Deprecated: Deprecate 10083841fb5SAndrew Jeffery Deprecated --> [*]: Remove 10183841fb5SAndrew Jeffery``` 10283841fb5SAndrew Jeffery 10383841fb5SAndrew JefferyThe ABI of the library produced by the build is controlled using the `abi` meson 10483841fb5SAndrew Jefferyoption. The following use cases determine how the `abi` option should be 10583841fb5SAndrew Jefferyspecified: 10683841fb5SAndrew Jeffery 10783841fb5SAndrew Jeffery| Use Case | Meson Configuration | 10883841fb5SAndrew Jeffery| ----------- | --------------------------------- | 10983841fb5SAndrew Jeffery| Production | `-Dabi=deprecated,stable` | 11083841fb5SAndrew Jeffery| Maintenance | `-Dabi=stable` | 11183841fb5SAndrew Jeffery| Development | `-Dabi=deprecated,stable,testing` | 11283841fb5SAndrew Jeffery 11383841fb5SAndrew Jeffery### Maintenance 11483841fb5SAndrew Jeffery 11583841fb5SAndrew JefferyApplications and libraries that depend on `libpldm` can identify how to migrate 11683841fb5SAndrew Jefferyoff of deprecated APIs by constraining the library ABI to the stable category. 11783841fb5SAndrew JefferyThis will force the compiler identify any call-sites that try to link against 11883841fb5SAndrew Jefferydeprecated symbols. 11983841fb5SAndrew Jeffery 12083841fb5SAndrew Jeffery### Development 12183841fb5SAndrew Jeffery 12283841fb5SAndrew JefferyApplications and libraries often require functionality that doesn't yet exist in 12383841fb5SAndrew Jeffery`libpldm`. The work is thus in two parts: 12483841fb5SAndrew Jeffery 12583841fb5SAndrew Jeffery1. Add the required APIs to `libpldm` 12683841fb5SAndrew Jeffery2. Use the new APIs from `libpldm` in the dependent application or library 12783841fb5SAndrew Jeffery 12883841fb5SAndrew JefferyAdding APIs to a library is a difficult task. Generally, once an API is exposed 12983841fb5SAndrew Jefferyin the library's ABI, any changes to the API risk breaking applications already 13083841fb5SAndrew Jefferymaking use of it. To make sure we have more than one shot at getting an API 13183841fb5SAndrew Jefferyright, all new APIs must first be exposed in the testing category. Concretely: 13283841fb5SAndrew Jeffery 13383841fb5SAndrew JefferyPatches adding new APIs MUST mark them as testing and MUST NOT mark them as 13483841fb5SAndrew Jefferystable. 13583841fb5SAndrew Jeffery 13683841fb5SAndrew Jeffery### Marking functions as testing, stable or deprecated 13783841fb5SAndrew Jeffery 138f89befe3SAndrew JefferyThree macros are provided through `config.h` (automatically included for all 139f89befe3SAndrew Jefferytranslation units) to mark functions as testing, stable or deprecated: 14083841fb5SAndrew Jeffery 14183841fb5SAndrew Jeffery1. `LIBPLDM_ABI_TESTING` 14283841fb5SAndrew Jeffery2. `LIBPLDM_ABI_STABLE` 14383841fb5SAndrew Jeffery3. `LIBPLDM_ABI_DEPRECATED` 14483841fb5SAndrew Jeffery 14583841fb5SAndrew JefferyThese annotations go immediately before your function signature: 14683841fb5SAndrew Jeffery 14783841fb5SAndrew Jeffery```c 14883841fb5SAndrew JefferyLIBPLDM_ABI_TESTING 14983841fb5SAndrew Jefferypldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport, 15083841fb5SAndrew Jeffery pldm_tid_t tid, 15183841fb5SAndrew Jeffery const void *pldm_req_msg, 15283841fb5SAndrew Jeffery size_t req_msg_len) 15383841fb5SAndrew Jeffery{ 15483841fb5SAndrew Jeffery ... 15583841fb5SAndrew Jeffery} 15683841fb5SAndrew Jeffery``` 15783841fb5SAndrew Jeffery 15883841fb5SAndrew Jeffery### Requirements for stabilising a function 15983841fb5SAndrew Jeffery 16083841fb5SAndrew JefferyAs mentioned above, all new functions must first be added in the testing 16183841fb5SAndrew Jefferycategory (using the `LIBPLDM_ABI_TESTING` annotation). 16283841fb5SAndrew Jeffery 16383841fb5SAndrew JefferyTo move a function from the testing category to the stable category, its 16483841fb5SAndrew Jefferyrequired that patches demonstrating use of the function in a dependent 16583841fb5SAndrew Jefferyapplication or library be linked in the commit message of the stabilisation 16683841fb5SAndrew Jefferychange. We require this to demonstrate that the implementer has considered its 16783841fb5SAndrew Jefferyuse in context _before_ preventing us from making changes to the API. 16883841fb5SAndrew Jeffery 16983841fb5SAndrew Jeffery### Building a dependent application or library against a testing ABI 17083841fb5SAndrew Jeffery 17183841fb5SAndrew JefferyMeson is broadly used in the OpenBMC ecosystem, the historical home of 17283841fb5SAndrew Jeffery`libpldm`. Meson's subprojects are a relatively painless way of managing 17383841fb5SAndrew Jefferydependencies for the purpose of developing complex applications and libraries. 17483841fb5SAndrew JefferyUse of `libpldm` as a subproject is both supported and encouraged. 17583841fb5SAndrew Jeffery 17683841fb5SAndrew Jeffery`libpldm`'s ABI can be controlled from a parent project through meson's 17783841fb5SAndrew Jefferysubproject configuration syntax: 17883841fb5SAndrew Jeffery 17983841fb5SAndrew Jeffery```shell 18083841fb5SAndrew Jeffery$ meson setup ... -Dlibpldm:abi=deprecated,stable,testing ... 18183841fb5SAndrew Jeffery``` 18283841fb5SAndrew Jeffery 1833896ecc7SManojkiran Eda## OEM/vendor-specific functions 184aa30d3efSPatrick Williams 1853896ecc7SManojkiran EdaThis will support OEM or vendor-specific functions and semantic information. 1863896ecc7SManojkiran EdaFollowing directory structure has to be used: 187aa30d3efSPatrick Williams 188aa30d3efSPatrick Williams```text 1893896ecc7SManojkiran Eda libpldm 1903896ecc7SManojkiran Eda |---- include/libpldm 191a8ede470SAndrew Jeffery | |---- oem/<oem_name> 1923896ecc7SManojkiran Eda | |----<oem based .h files> 1933896ecc7SManojkiran Eda |---- src 1943896ecc7SManojkiran Eda | |---- oem/<oem_name> 1953896ecc7SManojkiran Eda | |----<oem based .c files> 1963896ecc7SManojkiran Eda |---- tests 1973896ecc7SManojkiran Eda | |---- oem/<oem_name> 1983896ecc7SManojkiran Eda | |----<oem based test files> 1993896ecc7SManojkiran Eda 2003896ecc7SManojkiran Eda``` 201aa30d3efSPatrick Williams 202aa30d3efSPatrick Williams<oem_name> - This folder must be created with the name of the OEM/vendor in 203aa30d3efSPatrick Williamslower case. 2043896ecc7SManojkiran Eda 2053896ecc7SManojkiran EdaHeader files & source files having the oem functionality for the libpldm library 2063896ecc7SManojkiran Edashould be placed under the respective folder hierarchy as mentioned in the above 207aa30d3efSPatrick Williamsfigure. They must be adhering to the rules mentioned under the libpldm section 208aa30d3efSPatrick Williamsabove. 2093896ecc7SManojkiran Eda 210357ff921SGeorge LiuOnce the above is done a meson option has to be created in `meson.options` with 211357ff921SGeorge Liuits mapped compiler flag to enable conditional compilation. 2123896ecc7SManojkiran Eda 2133896ecc7SManojkiran EdaFor consistency would recommend using "oem-<oem_name>". 2143896ecc7SManojkiran Eda 215357ff921SGeorge LiuThe `meson.build` and the corresponding source file(s) will need to incorporate 216357ff921SGeorge Liuthe logic of adding its mapped compiler flag to allow conditional compilation of 217357ff921SGeorge Liuthe code. 218