libpldm: Explicit deprecated, stable and testing ABI classes

Experimenting with new APIs is important, but ABI stability of the
library is also important. We wish to have the freedom to add APIs
without being burdened by them being immediately set in stone.

We implement this wish by introducing three classes of ABI:

1. deprecated
2. stable
3. testing

These are enforced by corresponding function attributes:

1. LIBPLDM_ABI_DEPRECATED
2. LIBPLDM_ABI_STABLE
3. LIBPLDM_ABI_TESTING

Symbol visibility in the library is flipped to 'hidden' by default, so
one of these annotations must be used for the symbol to be exposed.

With these classes in place there are now clear points in time at which
we update the ABI dumps captured under the abi/ directory: When an API
is migrated from the 'testing' class to the 'stable' class, or when
removed from the 'deprecated' class.

Which classes of functions are exposed by the build is controlled by the
new 'abi' meson option. The option is of array type which contains the
list of ABI classes the build should consider. It defaults to enabling
all classes to provide test coverage in CI. The classes used should be
constrained to deprecated and stable (and not test) in any dependent
projects.

Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I25402e20c7be9c9f264f9ccd7ac36b384823734c
23 files changed
tree: 232d0788276128090bcb6f3b2852f9a98f3a239b
  1. abi/
  2. include/
  3. instance-db/
  4. src/
  5. subprojects/
  6. tests/
  7. .clang-format
  8. .clang-tidy
  9. CHANGELOG.md
  10. libpldm.pc.in
  11. LICENSE
  12. meson.build
  13. meson_options.txt
  14. OWNERS
  15. README.md
README.md

libpldm

This is a library which deals with the encoding and decoding of PLDM messages. It should be possible to use this library by projects other than OpenBMC, and hence certain constraints apply to it:

  • keeping it light weight
  • implementation in C
  • minimal dynamic memory allocations
  • endian-safe
  • no OpenBMC specific dependencies

Source files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c], etc.

Given a PLDM command "foo", the library will provide the following API: For the Requester function:

encode_foo_req() - encode a foo request
decode_foo_resp() - decode a response to foo

For the Responder function:

decode_foo_req() - decode a foo request
encode_foo_resp() - encode a response to foo

The library also provides API to pack and unpack PLDM headers.

To Build

Need meson and ninja. Alternatively, source an OpenBMC ARM/x86 SDK.

meson setup builddir && ninja -C builddir

To run unit tests

The simplest way of running the tests is as described by the meson man page:

meson setup builddir && meson test -C builddir

OEM/vendor-specific functions

This will support OEM or vendor-specific functions and semantic information. Following directory structure has to be used:

 libpldm
    |---- include/libpldm
    |        |---- oem/<oem_name>/libpldm
    |                    |----<oem based .h files>
    |---- src
    |        |---- oem/<oem_name>
    |                    |----<oem based .c files>
    |---- tests
    |        |---- oem/<oem_name>
    |                    |----<oem based test files>

<oem_name> - This folder must be created with the name of the OEM/vendor in lower case.

Header files & source files having the oem functionality for the libpldm library should be placed under the respective folder hierarchy as mentioned in the above figure. They must be adhering to the rules mentioned under the libpldm section above.

Once the above is done a meson option has to be created in libpldm/meson_options.txt with its mapped compiler flag to enable conditional compilation.

For consistency would recommend using "oem-<oem_name>".

The libpldm/meson.build and the corresponding source file(s) will need to incorporate the logic of adding its mapped compiler flag to allow conditional compilation of the code.

Requester APIs

The pldm requester API's are present in src/requester folder and they are intended to provide API's to interact with the desired underlying transport layer to send/receive pldm messages.

NOTE : In the current state, the requester API's in the repository only works with specific transport mechanism & these are going to change in future & probably aren't appropriate to be writing code against.