xref: /openbmc/pldm/README.md (revision a792b216) 
1# To Build
2Need `meson` and `ninja`. Alternatively, source an OpenBMC ARM/x86 SDK.
3```
4meson build && ninja -C build
5```
6## To run unit tests
7Tests can be run in the CI docker container, or with an OpenBMC x86 sdk(see
8below for x86 steps).
9```
10meson -Doe-sdk=enabled -Dtests=enabled build
11ninja -C build test
12```
13
14# Code Organization
15At a high-level, code in this repository belongs to one of the following three
16components.
17
18## libpldm
19This is a library which deals with the encoding and decoding of PLDM messages.
20It should be possible to use this library by projects other than OpenBMC, and
21hence certain constraints apply to it:
22- keeping it light weight
23- implementation in C
24- minimal dynamic memory allocations
25- endian-safe
26- no OpenBMC specific dependencies
27
28Source files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c],
29etc.
30
31Given a PLDM command "foo", the library will provide the following API:
32For the Requester function:
33```
34encode_foo_req() - encode a foo request
35decode_foo_resp() - decode a response to foo
36```
37For the Responder function:
38```
39decode_foo_req() - decode a foo request
40encode_foo_resp() - encode a response to foo
41```
42The library also provides API to pack and unpack PLDM headers.
43
44## libpldmresponder
45This library provides handlers for incoming PLDM request messages. It provides
46for a registration as well as a plug-in mechanism. The library is implemented in
47modern C++, and handles OpenBMC's platform specifics.
48
49The handlers are of the form
50```
51Response handler(Request payload, size_t payloadLen)
52```
53
54Source files are named according to the PLDM Type, for eg base.[hpp/cpp],
55fru.[hpp/cpp], etc.
56
57
58## OEM/vendor-specific functions
59This will support OEM or vendor-specific functions and semantic information.
60Following directory structure has to be used:
61```
62    pldm repo
63     |---- oem
64            |----<oem_name>
65                      |----libpldm
66                            |----<oem based encoding and decoding files>
67                      |----libpldmresponder
68                            |---<oem based handler files>
69
70```
71<oem_name> - This folder must be created with the name of the OEM/vendor
72in lower case. Folders named libpldm and libpldmresponder must be created under
73the folder <oem_name>
74
75Files having the oem functionality for the libpldm library should be placed
76under the folder oem/<oem_name>/libpldm. They must be adhering to the rules
77mentioned under the libpldm section above.
78
79Files having the oem functionality for the libpldmresponder library should be
80placed under the folder oem/<oem_name>/libpldmresponder. They must be adhering
81to the rules mentioned under the libpldmresponder section above.
82
83Once the above is done a conditional flag has to be created in the configure.ac
84to enable conditional compilation.
85
86For consistency would recommend using "--enable-oem-<oem_name>".
87
88The Makefile.am files in libpldm and libpldmresponder will need to be changed
89to allow conditional compilation of the code.
90
91## TODO
92Consider hosting libpldm above in a repo of its own, probably even outside the
93OpenBMC project? A separate repo would enable something like git submodule.
94
95# Flows
96This section documents important code flow paths.
97
98## BMC as PLDM responder
99a) PLDM daemon receives PLDM request message from underlying transport (MCTP).
100
101b) PLDM daemon routes message to message handler, based on the PLDM command.
102
103c) Message handler decodes request payload into various field(s) of the request
104   message. It can make use of a decode_foo_req() API, and doesn't have to
105   perform deserialization of the request payload by itself.
106
107d) Message handler works with the request field(s) and generates response
108   field(s).
109
110e) Message handler prepares a response message. It can make use of an
111   encode_foo_resp() API, and doesn't have to perform the serialization of the
112   response field(s) by itself.
113
114f) The PLDM daemon sends the response message prepared at step e) to the remote
115   PLDM device.
116
117## BMC as PLDM requester
118a) A BMC PLDM requester app prepares a PLDM request message. There would be
119   several requester apps (based on functionality/PLDM remote device). Each of
120   them needn't bother with the serialization of request field(s), and can
121   instead make use of an encode_foo_req() API.
122
123b) BMC requester app requests PLDM daemon to send the request message to remote
124   PLDM device.
125
126c) Once the PLDM daemon receives a corresponding response message, it notifies
127   the requester app.
128
129d) The requester app has to work with the response field(s). It can make use of
130   a decode_foo_resp() API to deserialize the response message.
131
132# PDR Implementation
133While PLDM Platform Descriptor Records (PDRs) are mostly static information,
134they can vary across platforms and systems. For this reason, platform specific
135PDR information is encoded in platform specific JSON files. JSON files must be
136named based on the PDR type number. For example a state effecter PDR JSON file
137will be named 11.json. The JSON files may also include information to enable
138additional processing (apart from PDR creation) for specific PDR types, for eg
139mapping an effecter id to a D-Bus object.
140
141The PLDM responder implementation finds and parses PDR JSON files to create the
142PDR repository. Platform specific PDR modifications would likely just result in
143JSON updates. New PDR type support would require JSON updates as well as PDR
144generation code. The PDR generator is a map of PDR Type -> C++ lambda to create
145PDR entries for that type based on the JSON, and to update the central PDR repo.
146