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