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