0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 ==================================
0004 PLDM Firmware Flash Update Library
0005 ==================================
0006
0007 ``pldmfw`` implements functionality for updating the flash on a device using
0008 the PLDM for Firmware Update standard
0009 <https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.
0010
0011 .. toctree::
0012 :maxdepth: 1
0013
0014 file-format
0015 driver-ops
0016
0017 ==================================
0018 Overview of the ``pldmfw`` library
0019 ==================================
0020
0021 The ``pldmfw`` library is intended to be used by device drivers for
0022 implementing device flash update based on firmware files following the PLDM
0023 firwmare file format.
0024
0025 It is implemented using an ops table that allows device drivers to provide
0026 the underlying device specific functionality.
0027
0028 ``pldmfw`` implements logic to parse the packed binary format of the PLDM
0029 firmware file into data structures, and then uses the provided function
0030 operations to determine if the firmware file is a match for the device. If
0031 so, it sends the record and component data to the firmware using the device
0032 specific implementations provided by device drivers. Once the device
0033 firmware indicates that the update may be performed, the firmware data is
0034 sent to the device for programming.
0035
0036 Parsing the PLDM file
0037 =====================
0038
0039 The PLDM file format uses packed binary data, with most multi-byte fields
0040 stored in the Little Endian format. Several pieces of data are variable
0041 length, including version strings and the number of records and components.
0042 Due to this, it is not straight forward to index the record, record
0043 descriptors, or components.
0044
0045 To avoid proliferating access to the packed binary data, the ``pldmfw``
0046 library parses and extracts this data into simpler structures for ease of
0047 access.
0048
0049 In order to safely process the firmware file, care is taken to avoid
0050 unaligned access of multi-byte fields, and to properly convert from Little
0051 Endian to CPU host format. Additionally the records, descriptors, and
0052 components are stored in linked lists.
0053
0054 Performing a flash update
0055 =========================
0056
0057 To perform a flash update, the ``pldmfw`` module performs the following
0058 steps
0059
0060 1. Parse the firmware file for record and component information
0061 2. Scan through the records and determine if the device matches any record
0062 in the file. The first matched record will be used.
0063 3. If the matching record provides package data, send this package data to
0064 the device.
0065 4. For each component that the record indicates, send the component data to
0066 the device. For each component, the firmware may respond with an
0067 indication of whether the update is suitable or not. If any component is
0068 not suitable, the update is canceled.
0069 5. For each component, send the binary data to the device firmware for
0070 updating.
0071 6. After all components are programmed, perform any final device-specific
0072 actions to finalize the update.
