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