1# PLDM - Platform Level Data Model 2 3[](LICENSE) 4 5## Overview 6 7PLDM (Platform Level Data Model) is a key component of the OpenBMC project, 8providing a standardized data model and message formats for various platform 9management functionalities. It defines a method to manage, monitor, and control 10the firmware and hardware of a system. 11 12The OpenBMC PLDM project aims to implement the specifications defined by the 13Distributed Management Task Force (DMTF), allowing for interoperable management 14interfaces across different hardware and firmware components. 15 16## Features 17 18- **Standardized Messaging:** Adheres to the DMTF's PLDM specifications, 19 enabling consistent and interoperable communication between different 20 components. 21- **Modularity:** Supports multiple PLDM types, including base, FRU,Firmware 22 update, Platform Monitoring and Control, and BIOS Control and Configuration. 23- **Extensibility:** Easily extendable to support new PLDM types and custom OEM 24 commands. 25- **Integration:** Seamlessly integrates with other OpenBMC components for 26 comprehensive system management. 27 28## Getting Started 29 30### Prerequisites 31 32To build and run PLDM, you need the following dependencies: 33 34- `Meson` 35- `Ninja` 36 37Alternatively, source an OpenBMC ARM/x86 SDK. 38 39### Building 40 41To build the PLDM project, follow these steps: 42 43```bash 44meson setup build && ninja -C build 45``` 46 47### To run unit tests 48 49The simplest way of running the tests is as described by the meson man page: 50 51```bash 52meson setup builddir && meson setup test -C builddir 53``` 54 55Alternatively, tests can be run in the OpenBMC CI docker container using 56[these](https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md) 57steps. 58 59### To enable pldm verbosity 60 61pldm daemon accepts a command line argument `--verbose` or `--v` or `-v` to 62enable the daemon to run in verbose mode. It can be done via adding this option 63to the environment file that pldm service consumes. 64 65```bash 66echo 'PLDMD_ARGS="--verbose"' > /etc/default/pldmd 67systemctl restart pldmd 68``` 69 70### To disable pldm verbosity 71 72```bash 73rm /etc/default/pldmd 74systemctl restart pldmd 75``` 76 77### Code Organization 78 79At a high-level, code in this repository belongs to one of the following three 80components. 81 82#### libpldmresponder 83 84This library provides handlers for incoming PLDM request messages. It provides 85for a registration as well as a plug-in mechanism. The library is implemented in 86modern C++, and handles OpenBMC's platform specifics. 87 88The handlers are of the form 89 90```c 91Response handler(Request payload, size_t payloadLen) 92``` 93 94Source files are named according to the PLDM Type, for eg base.[hpp/cpp], 95fru.[hpp/cpp], etc. 96 97#### OEM/vendor-specific functions 98 99This will support OEM or vendor-specific functions and semantic information. 100Following directory structure has to be used: 101 102```txt 103 pldm repo 104 |---- oem 105 |----<oem_name> 106 |----libpldmresponder 107 |---<oem based handler files> 108 109``` 110 111<oem_name> - This folder must be created with the name of the OEM/vendor in 112lower case. Folders named libpldm and libpldmresponder must be created under the 113folder <oem_name> 114 115Files having the oem functionality for the libpldmresponder library should be 116placed under the folder oem/<oem_name>/libpldmresponder. They must be adhering 117to the rules mentioned under the libpldmresponder section above. 118 119Once the above is done a meson option has to be created in 120`pldm/meson_options.txt` with its mapped compiler flag to enable conditional 121compilation. 122 123For consistency would recommend using "oem-<oem_name>". 124 125The `pldm/meson.build` and the corresponding source file(s) will need to 126incorporate the logic of adding its mapped compiler flag to allow conditional 127compilation of the code. 128 129##### libpldm 130 131pldm daemon links against the libpldm library during compilation, For more 132information on libpldm please refer to 133[libpldm](https://github.com/openbmc/libpldm) 134 135##### pldmtool 136 137For more information on pldmtool please refer to plmdtool/README.md. 138 139##### Flows 140 141This section documents important code flow paths. 142 143###### BMC as PLDM responder 144 145a) PLDM daemon receives PLDM request message from underlying transport (MCTP). 146 147b) PLDM daemon routes message to message handler, based on the PLDM command. 148 149c) Message handler decodes request payload into various field(s) of the request 150message. It can make use of a decode_foo_req() API, and doesn't have to perform 151deserialization of the request payload by itself. 152 153d) Message handler works with the request field(s) and generates response 154field(s). 155 156e) Message handler prepares a response message. It can make use of an 157encode_foo_resp() API, and doesn't have to perform the serialization of the 158response field(s) by itself. 159 160f) The PLDM daemon sends the response message prepared at step e) to the remote 161PLDM device. 162 163##### BMC as PLDM requester 164 165a) A BMC PLDM requester app prepares a PLDM request message. There would be 166several requester apps (based on functionality/PLDM remote device). Each of them 167needn't bother with the serialization of request field(s), and can instead make 168use of an encode_foo_req() API. 169 170b) BMC requester app requests PLDM daemon to send the request message to remote 171PLDM device. 172 173c) Once the PLDM daemon receives a corresponding response message, it notifies 174the requester app. 175 176d) The requester app has to work with the response field(s). It can make use of 177a decode_foo_resp() API to deserialize the response message. 178 179###### PDR Implementation 180 181While PLDM Platform Descriptor Records (PDRs) are mostly static information, 182they can vary across platforms and systems. For this reason, platform specific 183PDR information is encoded in platform specific JSON files. JSON files must be 184named based on the PDR type number. For example a state effecter PDR JSON file 185will be named 11.json. The JSON files may also include information to enable 186additional processing (apart from PDR creation) for specific PDR types, for eg 187mapping an effecter id to a D-Bus object. 188 189The PLDM responder implementation finds and parses PDR JSON files to create the 190PDR repository. Platform specific PDR modifications would likely just result in 191JSON updates. New PDR type support would require JSON updates as well as PDR 192generation code. The PDR generator is a map of PDR Type -> C++ lambda to create 193PDR entries for that type based on the JSON, and to update the central PDR repo. 194
){kind=link}