1.. SPDX-License-Identifier: GPL-2.0-only 2 3================================== 4PLDM Firmware Flash Update Library 5================================== 6 7``pldmfw`` implements functionality for updating the flash on a device using 8the PLDM for Firmware Update standard 9<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>. 10 11.. toctree:: 12 :maxdepth: 1 13 14 file-format 15 driver-ops 16 17Overview of the ``pldmfw`` library 18================================== 19 20The ``pldmfw`` library is intended to be used by device drivers for 21implementing device flash update based on firmware files following the PLDM 22firmware file format. 23 24It is implemented using an ops table that allows device drivers to provide 25the underlying device specific functionality. 26 27``pldmfw`` implements logic to parse the packed binary format of the PLDM 28firmware file into data structures, and then uses the provided function 29operations to determine if the firmware file is a match for the device. If 30so, it sends the record and component data to the firmware using the device 31specific implementations provided by device drivers. Once the device 32firmware indicates that the update may be performed, the firmware data is 33sent to the device for programming. 34 35Parsing the PLDM file 36===================== 37 38The PLDM file format uses packed binary data, with most multi-byte fields 39stored in the Little Endian format. Several pieces of data are variable 40length, including version strings and the number of records and components. 41Due to this, it is not straight forward to index the record, record 42descriptors, or components. 43 44To avoid proliferating access to the packed binary data, the ``pldmfw`` 45library parses and extracts this data into simpler structures for ease of 46access. 47 48In order to safely process the firmware file, care is taken to avoid 49unaligned access of multi-byte fields, and to properly convert from Little 50Endian to CPU host format. Additionally the records, descriptors, and 51components are stored in linked lists. 52 53Performing a flash update 54========================= 55 56To perform a flash update, the ``pldmfw`` module performs the following 57steps 58 591. Parse the firmware file for record and component information 602. Scan through the records and determine if the device matches any record 61 in the file. The first matched record will be used. 623. If the matching record provides package data, send this package data to 63 the device. 644. For each component that the record indicates, send the component data to 65 the device. For each component, the firmware may respond with an 66 indication of whether the update is suitable or not. If any component is 67 not suitable, the update is canceled. 685. For each component, send the binary data to the device firmware for 69 updating. 706. After all components are programmed, perform any final device-specific 71 actions to finalize the update. 72