xref: /openbmc/pldm/README.md (revision 4d99c311) 
1# To Build
2
3Need `meson` and `ninja`. Alternatively, source an OpenBMC ARM/x86 SDK.
4
5```
6meson setup build && ninja -C build
7```
8
9## To run unit tests
10
11The simplest way of running the tests is as described by the meson man page:
12
13```
14meson setup builddir && meson setup test -C builddir
15```
16
17Alternatively, tests can be run in the OpenBMC CI docker container, or with an
18OpenBMC x86 sdk(see below for x86 steps).
19
20```
21meson setup -Doe-sdk=enabled build
22ninja -C build test
23```
24
25## To enable pldm verbosity
26
27pldm daemon accepts a command line argument `--verbose` or `--v` or `-v` to
28enable the daemon to run in verbose mode. It can be done via adding this option
29to the environment file that pldm service consumes.
30
31```
32echo 'PLDMD_ARGS="--verbose"' > /etc/default/pldmd
33systemctl restart pldmd
34```
35
36## To disable pldm verbosity
37
38```
39rm /etc/default/pldmd
40systemctl restart pldmd
41```
42
43# Code Organization
44
45At a high-level, code in this repository belongs to one of the following three
46components.
47
48## libpldmresponder
49
50This library provides handlers for incoming PLDM request messages. It provides
51for a registration as well as a plug-in mechanism. The library is implemented in
52modern C++, and handles OpenBMC's platform specifics.
53
54The handlers are of the form
55
56```
57Response handler(Request payload, size_t payloadLen)
58```
59
60Source files are named according to the PLDM Type, for eg base.[hpp/cpp],
61fru.[hpp/cpp], etc.
62
63## OEM/vendor-specific functions
64
65This will support OEM or vendor-specific functions and semantic information.
66Following directory structure has to be used:
67
68```
69    pldm repo
70     |---- oem
71            |----<oem_name>
72                      |----libpldmresponder
73                            |---<oem based handler files>
74
75```
76
77<oem_name> - This folder must be created with the name of the OEM/vendor in
78lower case. Folders named libpldm and libpldmresponder must be created under the
79folder <oem_name>
80
81Files having the oem functionality for the libpldmresponder library should be
82placed under the folder oem/<oem_name>/libpldmresponder. They must be adhering
83to the rules mentioned under the libpldmresponder section above.
84
85Once the above is done a meson option has to be created in
86`pldm/meson_options.txt` with its mapped compiler flag to enable conditional
87compilation.
88
89For consistency would recommend using "oem-<oem_name>".
90
91The `pldm/meson.build` and the corresponding source file(s) will need to
92incorporate the logic of adding its mapped compiler flag to allow conditional
93compilation of the code.
94
95## libpldm
96
97pldm daemon links against the libpldm library during compilation, For more
98information on libpldm please refer to
99[libpldm](https://github.com/openbmc/libpldm)
100
101## pldmtool
102
103For more information on pldmtool please refer to plmdtool/README.md.
104
105# Flows
106
107This section documents important code flow paths.
108
109## BMC as PLDM responder
110
111a) PLDM daemon receives PLDM request message from underlying transport (MCTP).
112
113b) PLDM daemon routes message to message handler, based on the PLDM command.
114
115c) Message handler decodes request payload into various field(s) of the request
116message. It can make use of a decode_foo_req() API, and doesn't have to perform
117deserialization of the request payload by itself.
118
119d) Message handler works with the request field(s) and generates response
120field(s).
121
122e) Message handler prepares a response message. It can make use of an
123encode_foo_resp() API, and doesn't have to perform the serialization of the
124response field(s) by itself.
125
126f) The PLDM daemon sends the response message prepared at step e) to the remote
127PLDM device.
128
129## BMC as PLDM requester
130
131a) A BMC PLDM requester app prepares a PLDM request message. There would be
132several requester apps (based on functionality/PLDM remote device). Each of them
133needn't bother with the serialization of request field(s), and can instead make
134use of an encode_foo_req() API.
135
136b) BMC requester app requests PLDM daemon to send the request message to remote
137PLDM device.
138
139c) Once the PLDM daemon receives a corresponding response message, it notifies
140the requester app.
141
142d) The requester app has to work with the response field(s). It can make use of
143a decode_foo_resp() API to deserialize the response message.
144
145# PDR Implementation
146
147While PLDM Platform Descriptor Records (PDRs) are mostly static information,
148they can vary across platforms and systems. For this reason, platform specific
149PDR information is encoded in platform specific JSON files. JSON files must be
150named based on the PDR type number. For example a state effecter PDR JSON file
151will be named 11.json. The JSON files may also include information to enable
152additional processing (apart from PDR creation) for specific PDR types, for eg
153mapping an effecter id to a D-Bus object.
154
155The PLDM responder implementation finds and parses PDR JSON files to create the
156PDR repository. Platform specific PDR modifications would likely just result in
157JSON updates. New PDR type support would require JSON updates as well as PDR
158generation code. The PDR generator is a map of PDR Type -> C++ lambda to create
159PDR entries for that type based on the JSON, and to update the central PDR repo.
160