1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0-only 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun================================== 4*4882a593SmuzhiyunPLDM Firmware Flash Update Library 5*4882a593Smuzhiyun================================== 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun``pldmfw`` implements functionality for updating the flash on a device using 8*4882a593Smuzhiyunthe PLDM for Firmware Update standard 9*4882a593Smuzhiyun<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>. 10*4882a593Smuzhiyun 11*4882a593Smuzhiyun.. toctree:: 12*4882a593Smuzhiyun :maxdepth: 1 13*4882a593Smuzhiyun 14*4882a593Smuzhiyun file-format 15*4882a593Smuzhiyun driver-ops 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun================================== 18*4882a593SmuzhiyunOverview of the ``pldmfw`` library 19*4882a593Smuzhiyun================================== 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunThe ``pldmfw`` library is intended to be used by device drivers for 22*4882a593Smuzhiyunimplementing device flash update based on firmware files following the PLDM 23*4882a593Smuzhiyunfirwmare file format. 24*4882a593Smuzhiyun 25*4882a593SmuzhiyunIt is implemented using an ops table that allows device drivers to provide 26*4882a593Smuzhiyunthe underlying device specific functionality. 27*4882a593Smuzhiyun 28*4882a593Smuzhiyun``pldmfw`` implements logic to parse the packed binary format of the PLDM 29*4882a593Smuzhiyunfirmware file into data structures, and then uses the provided function 30*4882a593Smuzhiyunoperations to determine if the firmware file is a match for the device. If 31*4882a593Smuzhiyunso, it sends the record and component data to the firmware using the device 32*4882a593Smuzhiyunspecific implementations provided by device drivers. Once the device 33*4882a593Smuzhiyunfirmware indicates that the update may be performed, the firmware data is 34*4882a593Smuzhiyunsent to the device for programming. 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunParsing the PLDM file 37*4882a593Smuzhiyun===================== 38*4882a593Smuzhiyun 39*4882a593SmuzhiyunThe PLDM file format uses packed binary data, with most multi-byte fields 40*4882a593Smuzhiyunstored in the Little Endian format. Several pieces of data are variable 41*4882a593Smuzhiyunlength, including version strings and the number of records and components. 42*4882a593SmuzhiyunDue to this, it is not straight forward to index the record, record 43*4882a593Smuzhiyundescriptors, or components. 44*4882a593Smuzhiyun 45*4882a593SmuzhiyunTo avoid proliferating access to the packed binary data, the ``pldmfw`` 46*4882a593Smuzhiyunlibrary parses and extracts this data into simpler structures for ease of 47*4882a593Smuzhiyunaccess. 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunIn order to safely process the firmware file, care is taken to avoid 50*4882a593Smuzhiyununaligned access of multi-byte fields, and to properly convert from Little 51*4882a593SmuzhiyunEndian to CPU host format. Additionally the records, descriptors, and 52*4882a593Smuzhiyuncomponents are stored in linked lists. 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunPerforming a flash update 55*4882a593Smuzhiyun========================= 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunTo perform a flash update, the ``pldmfw`` module performs the following 58*4882a593Smuzhiyunsteps 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun1. Parse the firmware file for record and component information 61*4882a593Smuzhiyun2. Scan through the records and determine if the device matches any record 62*4882a593Smuzhiyun in the file. The first matched record will be used. 63*4882a593Smuzhiyun3. If the matching record provides package data, send this package data to 64*4882a593Smuzhiyun the device. 65*4882a593Smuzhiyun4. For each component that the record indicates, send the component data to 66*4882a593Smuzhiyun the device. For each component, the firmware may respond with an 67*4882a593Smuzhiyun indication of whether the update is suitable or not. If any component is 68*4882a593Smuzhiyun not suitable, the update is canceled. 69*4882a593Smuzhiyun5. For each component, send the binary data to the device firmware for 70*4882a593Smuzhiyun updating. 71*4882a593Smuzhiyun6. After all components are programmed, perform any final device-specific 72*4882a593Smuzhiyun actions to finalize the update. 73