1b8265621SJacob Keller.. SPDX-License-Identifier: GPL-2.0-only 2b8265621SJacob Keller 3b8265621SJacob Keller================================== 4b8265621SJacob KellerPLDM Firmware Flash Update Library 5b8265621SJacob Keller================================== 6b8265621SJacob Keller 7b8265621SJacob Keller``pldmfw`` implements functionality for updating the flash on a device using 8b8265621SJacob Kellerthe PLDM for Firmware Update standard 9b8265621SJacob Keller<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>. 10b8265621SJacob Keller 11b8265621SJacob Keller.. toctree:: 12b8265621SJacob Keller :maxdepth: 1 13b8265621SJacob Keller 14b8265621SJacob Keller file-format 15b8265621SJacob Keller driver-ops 16b8265621SJacob Keller 17b8265621SJacob Keller================================== 18b8265621SJacob KellerOverview of the ``pldmfw`` library 19b8265621SJacob Keller================================== 20b8265621SJacob Keller 21b8265621SJacob KellerThe ``pldmfw`` library is intended to be used by device drivers for 22b8265621SJacob Kellerimplementing device flash update based on firmware files following the PLDM 23*7852fe3aSRandy Dunlapfirmware file format. 24b8265621SJacob Keller 25b8265621SJacob KellerIt is implemented using an ops table that allows device drivers to provide 26b8265621SJacob Kellerthe underlying device specific functionality. 27b8265621SJacob Keller 28b8265621SJacob Keller``pldmfw`` implements logic to parse the packed binary format of the PLDM 29b8265621SJacob Kellerfirmware file into data structures, and then uses the provided function 30b8265621SJacob Kelleroperations to determine if the firmware file is a match for the device. If 31b8265621SJacob Kellerso, it sends the record and component data to the firmware using the device 32b8265621SJacob Kellerspecific implementations provided by device drivers. Once the device 33b8265621SJacob Kellerfirmware indicates that the update may be performed, the firmware data is 34b8265621SJacob Kellersent to the device for programming. 35b8265621SJacob Keller 36b8265621SJacob KellerParsing the PLDM file 37b8265621SJacob Keller===================== 38b8265621SJacob Keller 39b8265621SJacob KellerThe PLDM file format uses packed binary data, with most multi-byte fields 40b8265621SJacob Kellerstored in the Little Endian format. Several pieces of data are variable 41b8265621SJacob Kellerlength, including version strings and the number of records and components. 42b8265621SJacob KellerDue to this, it is not straight forward to index the record, record 43b8265621SJacob Kellerdescriptors, or components. 44b8265621SJacob Keller 45b8265621SJacob KellerTo avoid proliferating access to the packed binary data, the ``pldmfw`` 46b8265621SJacob Kellerlibrary parses and extracts this data into simpler structures for ease of 47b8265621SJacob Kelleraccess. 48b8265621SJacob Keller 49b8265621SJacob KellerIn order to safely process the firmware file, care is taken to avoid 50b8265621SJacob Kellerunaligned access of multi-byte fields, and to properly convert from Little 51b8265621SJacob KellerEndian to CPU host format. Additionally the records, descriptors, and 52b8265621SJacob Kellercomponents are stored in linked lists. 53b8265621SJacob Keller 54b8265621SJacob KellerPerforming a flash update 55b8265621SJacob Keller========================= 56b8265621SJacob Keller 57b8265621SJacob KellerTo perform a flash update, the ``pldmfw`` module performs the following 58b8265621SJacob Kellersteps 59b8265621SJacob Keller 60b8265621SJacob Keller1. Parse the firmware file for record and component information 61b8265621SJacob Keller2. Scan through the records and determine if the device matches any record 62b8265621SJacob Keller in the file. The first matched record will be used. 63b8265621SJacob Keller3. If the matching record provides package data, send this package data to 64b8265621SJacob Keller the device. 65b8265621SJacob Keller4. For each component that the record indicates, send the component data to 66b8265621SJacob Keller the device. For each component, the firmware may respond with an 67b8265621SJacob Keller indication of whether the update is suitable or not. If any component is 68b8265621SJacob Keller not suitable, the update is canceled. 69b8265621SJacob Keller5. For each component, send the binary data to the device firmware for 70b8265621SJacob Keller updating. 71b8265621SJacob Keller6. After all components are programmed, perform any final device-specific 72b8265621SJacob Keller actions to finalize the update. 73