xref: /openbmc/pldm/README.md (revision 7f57f441) 
1# Code Organization
2At a high-level, code in this repository belongs to one of the following three
3components.
4
5## libpldm
6This is a library which deals with the encoding and decoding of PLDM messages.
7It should be possible to use this library by projects other than OpenBMC, and
8hence certain constraints apply to it:
9- keeping it light weight
10- implementation in C
11- minimal dynamic memory allocations
12- endian-safe
13- no OpenBMC specific dependencies
14
15Source files are named according to the PLDM Type, for eg base.[h/c], fru.[h/c],
16etc.
17
18Given a PLDM command "foo", the library will provide the following API:
19For the Requester function:
20```
21encode_foo_req() - encode a foo request
22decode_foo_resp() - decode a response to foo
23```
24For the Responder function:
25```
26decode_foo_req() - decode a foo request
27encode_foo_resp() - encode a response to foo
28```
29The library also provides API to pack and unpack PLDM headers.
30
31## libpldmresponder
32This library provides handlers for incoming PLDM request messages. It provides
33for a registration as well as a plug-in mechanism. The library is implemented in
34modern C++, and handles OpenBMC's platform specifics.
35
36The handlers are of the form
37```
38Response handler(Request payload, size_t payloadLen)
39```
40
41Source files are named according to the PLDM Type, for eg base.[hpp/cpp],
42fru.[hpp/cpp], etc.
43
44
45## OEM/vendor-specific functions
46This will support OEM or vendor-specific functions and semantic information.
47Following directory structure has to be used:
48```
49    pldm repo
50     |---- oem
51            |----<oem_name>
52                      |----libpldm
53                            |----<oem based encoding and decoding files>
54                      |----libpldmresponder
55                            |---<oem based handler files>
56
57```
58<oem_name> - This folder must be created with the name of the OEM/vendor
59in lower case. Folders named libpldm and libpldmresponder must be created under
60the folder <oem_name>
61
62Files having the oem functionality for the libpldm library should be placed
63under the folder oem/<oem_name>/libpldm. They must be adhering to the rules
64mentioned under the libpldm section above.
65
66Files having the oem functionality for the libpldmresponder library should be
67placed under the folder oem/<oem_name>/libpldmresponder. They must be adhering
68to the rules mentioned under the libpldmresponder section above.
69
70Once the above is done a conditional flag has to be created in the configure.ac
71to enable conditional compilation.
72
73For consistency would recommend using "--enable-oem-<oem_name>".
74
75The Makefile.am files in libpldm and libpldmresponder will need to be changed
76to allow conditional compilation of the code.
77
78## TODO
79Consider hosting libpldm above in a repo of its own, probably even outside the
80OpenBMC project? A separate repo would enable something like git submodule.
81
82# Flows
83This section documents important code flow paths.
84
85## BMC as PLDM responder
86a) PLDM daemon receives PLDM request message from underlying transport (MCTP).
87
88b) PLDM daemon routes message to message handler, based on the PLDM command.
89
90c) Message handler decodes request payload into various field(s) of the request
91   message. It can make use of a decode_foo_req() API, and doesn't have to
92   perform deserialization of the request payload by itself.
93
94d) Message handler works with the request field(s) and generates response
95   field(s).
96
97e) Message handler prepares a response message. It can make use of an
98   encode_foo_resp() API, and doesn't have to perform the serialization of the
99   response field(s) by itself.
100
101f) The PLDM daemon sends the response message prepared at step e) to the remote
102   PLDM device.
103
104## BMC as PLDM requester
105a) A BMC PLDM requester app prepares a PLDM request message. There would be
106   several requester apps (based on functionality/PLDM remote device). Each of
107   them needn't bother with the serialization of request field(s), and can
108   instead make use of an encode_foo_req() API.
109
110b) BMC requester app requests PLDM daemon to send the request message to remote
111   PLDM device.
112
113c) Once the PLDM daemon receives a corresponding response message, it notifies
114   the requester app.
115
116d) The requester app has to work with the response field(s). It can make use of
117   a decode_foo_resp() API to deserialize the response message.
118