xref: /openbmc/pldm/README.md (revision d8da2089) 
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 meson option has to be created in
84`pldm/meson_options.txt` with its mapped compiler flag to enable conditional
85compilation.
86
87For consistency would recommend using "oem-<oem_name>".
88
89The `pldm/meson.build` and the corresponding source file(s) will need to
90incorporate the logic of adding its mapped compiler flag to allow conditional
91compilation of the code.
92
93## TODO
94Consider hosting libpldm above in a repo of its own, probably even outside the
95OpenBMC project? A separate repo would enable something like git submodule.
96
97# Flows
98This section documents important code flow paths.
99
100## BMC as PLDM responder
101a) PLDM daemon receives PLDM request message from underlying transport (MCTP).
102
103b) PLDM daemon routes message to message handler, based on the PLDM command.
104
105c) Message handler decodes request payload into various field(s) of the request
106   message. It can make use of a decode_foo_req() API, and doesn't have to
107   perform deserialization of the request payload by itself.
108
109d) Message handler works with the request field(s) and generates response
110   field(s).
111
112e) Message handler prepares a response message. It can make use of an
113   encode_foo_resp() API, and doesn't have to perform the serialization of the
114   response field(s) by itself.
115
116f) The PLDM daemon sends the response message prepared at step e) to the remote
117   PLDM device.
118
119## BMC as PLDM requester
120a) A BMC PLDM requester app prepares a PLDM request message. There would be
121   several requester apps (based on functionality/PLDM remote device). Each of
122   them needn't bother with the serialization of request field(s), and can
123   instead make use of an encode_foo_req() API.
124
125b) BMC requester app requests PLDM daemon to send the request message to remote
126   PLDM device.
127
128c) Once the PLDM daemon receives a corresponding response message, it notifies
129   the requester app.
130
131d) The requester app has to work with the response field(s). It can make use of
132   a decode_foo_resp() API to deserialize the response message.
133
134# PDR Implementation
135While PLDM Platform Descriptor Records (PDRs) are mostly static information,
136they can vary across platforms and systems. For this reason, platform specific
137PDR information is encoded in platform specific JSON files. JSON files must be
138named based on the PDR type number. For example a state effecter PDR JSON file
139will be named 11.json. The JSON files may also include information to enable
140additional processing (apart from PDR creation) for specific PDR types, for eg
141mapping an effecter id to a D-Bus object.
142
143The PLDM responder implementation finds and parses PDR JSON files to create the
144PDR repository. Platform specific PDR modifications would likely just result in
145JSON updates. New PDR type support would require JSON updates as well as PDR
146generation code. The PDR generator is a map of PDR Type -> C++ lambda to create
147PDR entries for that type based on the JSON, and to update the central PDR repo.
148