Documentation/driver-api/pldmfw/index.rst

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