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 51The ABIs (symbols, generally functions) exposed by the library are separated 52into three categories: 53 541. Stable 552. Testing 563. Deprecated 57 58Applications depending on `libpldm` should aim to only use functions from the 59stable category. However, this may not always be possible. What to do when 60required functions fall into the deprecated or testing categories is outlined 61below. 62 63### The ABI lifecycle 64 65```mermaid 66--- 67title: libpldm symbol lifecycle 68--- 69stateDiagram-v2 70 direction LR 71 [*] --> Testing: Add 72 Testing --> Testing: Change 73 Testing --> [*]: Remove 74 Testing --> Stable: Stabilise 75 Stable --> Deprecated: Deprecate 76 Deprecated --> [*]: Remove 77``` 78 79The ABI of the library produced by the build is controlled using the `abi` meson 80option. The following use cases determine how the `abi` option should be 81specified: 82 83| Use Case | Meson Configuration | 84| ----------- | --------------------------------- | 85| Production | `-Dabi=deprecated,stable` | 86| Maintenance | `-Dabi=stable` | 87| Development | `-Dabi=deprecated,stable,testing` | 88 89### Maintenance 90 91Applications and libraries that depend on `libpldm` can identify how to migrate 92off of deprecated APIs by constraining the library ABI to the stable category. 93This will force the compiler identify any call-sites that try to link against 94deprecated symbols. 95 96### Development 97 98Applications and libraries often require functionality that doesn't yet exist in 99`libpldm`. The work is thus in two parts: 100 1011. Add the required APIs to `libpldm` 1022. Use the new APIs from `libpldm` in the dependent application or library 103 104Adding APIs to a library is a difficult task. Generally, once an API is exposed 105in the library's ABI, any changes to the API risk breaking applications already 106making use of it. To make sure we have more than one shot at getting an API 107right, all new APIs must first be exposed in the testing category. Concretely: 108 109Patches adding new APIs MUST mark them as testing and MUST NOT mark them as 110stable. 111 112### Marking functions as testing, stable or deprecated 113 114Three macros are provided through `config.h` (automatically included for all 115translation units) to mark functions as testing, stable or deprecated: 116 1171. `LIBPLDM_ABI_TESTING` 1182. `LIBPLDM_ABI_STABLE` 1193. `LIBPLDM_ABI_DEPRECATED` 120 121These annotations go immediately before your function signature: 122 123```c 124LIBPLDM_ABI_TESTING 125pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport, 126 pldm_tid_t tid, 127 const void *pldm_req_msg, 128 size_t req_msg_len) 129{ 130 ... 131} 132``` 133 134### Requirements for stabilising a function 135 136As mentioned above, all new functions must first be added in the testing 137category (using the `LIBPLDM_ABI_TESTING` annotation). 138 139To move a function from the testing category to the stable category, its 140required that patches demonstrating use of the function in a dependent 141application or library be linked in the commit message of the stabilisation 142change. We require this to demonstrate that the implementer has considered its 143use in context _before_ preventing us from making changes to the API. 144 145### Building a dependent application or library against a testing ABI 146 147Meson is broadly used in the OpenBMC ecosystem, the historical home of 148`libpldm`. Meson's subprojects are a relatively painless way of managing 149dependencies for the purpose of developing complex applications and libraries. 150Use of `libpldm` as a subproject is both supported and encouraged. 151 152`libpldm`'s ABI can be controlled from a parent project through meson's 153subproject configuration syntax: 154 155```shell 156$ meson setup ... -Dlibpldm:abi=deprecated,stable,testing ... 157``` 158 159## OEM/vendor-specific functions 160 161This will support OEM or vendor-specific functions and semantic information. 162Following directory structure has to be used: 163 164```text 165 libpldm 166 |---- include/libpldm 167 | |---- oem/<oem_name>/libpldm 168 | |----<oem based .h files> 169 |---- src 170 | |---- oem/<oem_name> 171 | |----<oem based .c files> 172 |---- tests 173 | |---- oem/<oem_name> 174 | |----<oem based test files> 175 176``` 177 178<oem_name> - This folder must be created with the name of the OEM/vendor in 179lower case. 180 181Header files & source files having the oem functionality for the libpldm library 182should be placed under the respective folder hierarchy as mentioned in the above 183figure. They must be adhering to the rules mentioned under the libpldm section 184above. 185 186Once the above is done a meson option has to be created in 187`libpldm/meson_options.txt` with its mapped compiler flag to enable conditional 188compilation. 189 190For consistency would recommend using "oem-<oem_name>". 191 192The `libpldm/meson.build` and the corresponding source file(s) will need to 193incorporate the logic of adding its mapped compiler flag to allow conditional 194compilation of the code. 195 196## Requester APIs 197 198The pldm requester API's are present in `src/requester` folder and they are 199intended to provide API's to interact with the desired underlying transport 200layer to send/receive pldm messages. 201 202**NOTE** : In the current state, the requester API's in the repository only 203works with [specific transport mechanism](https://github.com/openbmc/libmctp) & 204these are going to change in future & probably aren't appropriate to be writing 205code against. 206