73 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-only2 3==================================4PLDM Firmware Flash Update Library5==================================6 7``pldmfw`` implements functionality for updating the flash on a device using8the PLDM for Firmware Update standard9<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.10 11.. toctree::12 :maxdepth: 113 14 file-format15 driver-ops16 17==================================18Overview of the ``pldmfw`` library19==================================20 21The ``pldmfw`` library is intended to be used by device drivers for22implementing device flash update based on firmware files following the PLDM23firmware file format.24 25It is implemented using an ops table that allows device drivers to provide26the underlying device specific functionality.27 28``pldmfw`` implements logic to parse the packed binary format of the PLDM29firmware file into data structures, and then uses the provided function30operations to determine if the firmware file is a match for the device. If31so, it sends the record and component data to the firmware using the device32specific implementations provided by device drivers. Once the device33firmware indicates that the update may be performed, the firmware data is34sent to the device for programming.35 36Parsing the PLDM file37=====================38 39The PLDM file format uses packed binary data, with most multi-byte fields40stored in the Little Endian format. Several pieces of data are variable41length, including version strings and the number of records and components.42Due to this, it is not straight forward to index the record, record43descriptors, or components.44 45To avoid proliferating access to the packed binary data, the ``pldmfw``46library parses and extracts this data into simpler structures for ease of47access.48 49In order to safely process the firmware file, care is taken to avoid50unaligned access of multi-byte fields, and to properly convert from Little51Endian to CPU host format. Additionally the records, descriptors, and52components are stored in linked lists.53 54Performing a flash update55=========================56 57To perform a flash update, the ``pldmfw`` module performs the following58steps59 601. Parse the firmware file for record and component information612. Scan through the records and determine if the device matches any record62 in the file. The first matched record will be used.633. If the matching record provides package data, send this package data to64 the device.654. For each component that the record indicates, send the component data to66 the device. For each component, the firmware may respond with an67 indication of whether the update is suitable or not. If any component is68 not suitable, the update is canceled.695. For each component, send the binary data to the device firmware for70 updating.716. After all components are programmed, perform any final device-specific72 actions to finalize the update.73