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` to mark functions as testing, 115stable 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 124#include "config.h" 125 126... 127 128LIBPLDM_ABI_TESTING 129pldm_requester_rc_t pldm_transport_send_msg(struct pldm_transport *transport, 130 pldm_tid_t tid, 131 const void *pldm_req_msg, 132 size_t req_msg_len) 133{ 134 ... 135} 136``` 137 138### Requirements for stabilising a function 139 140As mentioned above, all new functions must first be added in the testing 141category (using the `LIBPLDM_ABI_TESTING` annotation). 142 143To move a function from the testing category to the stable category, its 144required that patches demonstrating use of the function in a dependent 145application or library be linked in the commit message of the stabilisation 146change. We require this to demonstrate that the implementer has considered its 147use in context _before_ preventing us from making changes to the API. 148 149### Building a dependent application or library against a testing ABI 150 151Meson is broadly used in the OpenBMC ecosystem, the historical home of 152`libpldm`. Meson's subprojects are a relatively painless way of managing 153dependencies for the purpose of developing complex applications and libraries. 154Use of `libpldm` as a subproject is both supported and encouraged. 155 156`libpldm`'s ABI can be controlled from a parent project through meson's 157subproject configuration syntax: 158 159```shell 160$ meson setup ... -Dlibpldm:abi=deprecated,stable,testing ... 161``` 162 163## OEM/vendor-specific functions 164 165This will support OEM or vendor-specific functions and semantic information. 166Following directory structure has to be used: 167 168```text 169 libpldm 170 |---- include/libpldm 171 | |---- oem/<oem_name>/libpldm 172 | |----<oem based .h files> 173 |---- src 174 | |---- oem/<oem_name> 175 | |----<oem based .c files> 176 |---- tests 177 | |---- oem/<oem_name> 178 | |----<oem based test files> 179 180``` 181 182<oem_name> - This folder must be created with the name of the OEM/vendor in 183lower case. 184 185Header files & source files having the oem functionality for the libpldm library 186should be placed under the respective folder hierarchy as mentioned in the above 187figure. They must be adhering to the rules mentioned under the libpldm section 188above. 189 190Once the above is done a meson option has to be created in 191`libpldm/meson_options.txt` with its mapped compiler flag to enable conditional 192compilation. 193 194For consistency would recommend using "oem-<oem_name>". 195 196The `libpldm/meson.build` and the corresponding source file(s) will need to 197incorporate the logic of adding its mapped compiler flag to allow conditional 198compilation of the code. 199 200## Requester APIs 201 202The pldm requester API's are present in `src/requester` folder and they are 203intended to provide API's to interact with the desired underlying transport 204layer to send/receive pldm messages. 205 206**NOTE** : In the current state, the requester API's in the repository only 207works with [specific transport mechanism](https://github.com/openbmc/libmctp) & 208these are going to change in future & probably aren't appropriate to be writing 209code against. 210