1b8265621SJacob Keller.. SPDX-License-Identifier: GPL-2.0-only
2b8265621SJacob Keller
3b8265621SJacob Keller==================================
4b8265621SJacob KellerPLDM Firmware Flash Update Library
5b8265621SJacob Keller==================================
6b8265621SJacob Keller
7b8265621SJacob Keller``pldmfw`` implements functionality for updating the flash on a device using
8b8265621SJacob Kellerthe PLDM for Firmware Update standard
9b8265621SJacob Keller<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.
10b8265621SJacob Keller
11b8265621SJacob Keller.. toctree::
12b8265621SJacob Keller   :maxdepth: 1
13b8265621SJacob Keller
14b8265621SJacob Keller   file-format
15b8265621SJacob Keller   driver-ops
16b8265621SJacob Keller
17b8265621SJacob Keller==================================
18b8265621SJacob KellerOverview of the ``pldmfw`` library
19b8265621SJacob Keller==================================
20b8265621SJacob Keller
21b8265621SJacob KellerThe ``pldmfw`` library is intended to be used by device drivers for
22b8265621SJacob Kellerimplementing device flash update based on firmware files following the PLDM
23*7852fe3aSRandy Dunlapfirmware file format.
24b8265621SJacob Keller
25b8265621SJacob KellerIt is implemented using an ops table that allows device drivers to provide
26b8265621SJacob Kellerthe underlying device specific functionality.
27b8265621SJacob Keller
28b8265621SJacob Keller``pldmfw`` implements logic to parse the packed binary format of the PLDM
29b8265621SJacob Kellerfirmware file into data structures, and then uses the provided function
30b8265621SJacob Kelleroperations to determine if the firmware file is a match for the device. If
31b8265621SJacob Kellerso, it sends the record and component data to the firmware using the device
32b8265621SJacob Kellerspecific implementations provided by device drivers. Once the device
33b8265621SJacob Kellerfirmware indicates that the update may be performed, the firmware data is
34b8265621SJacob Kellersent to the device for programming.
35b8265621SJacob Keller
36b8265621SJacob KellerParsing the PLDM file
37b8265621SJacob Keller=====================
38b8265621SJacob Keller
39b8265621SJacob KellerThe PLDM file format uses packed binary data, with most multi-byte fields
40b8265621SJacob Kellerstored in the Little Endian format. Several pieces of data are variable
41b8265621SJacob Kellerlength, including version strings and the number of records and components.
42b8265621SJacob KellerDue to this, it is not straight forward to index the record, record
43b8265621SJacob Kellerdescriptors, or components.
44b8265621SJacob Keller
45b8265621SJacob KellerTo avoid proliferating access to the packed binary data, the ``pldmfw``
46b8265621SJacob Kellerlibrary parses and extracts this data into simpler structures for ease of
47b8265621SJacob Kelleraccess.
48b8265621SJacob Keller
49b8265621SJacob KellerIn order to safely process the firmware file, care is taken to avoid
50b8265621SJacob Kellerunaligned access of multi-byte fields, and to properly convert from Little
51b8265621SJacob KellerEndian to CPU host format. Additionally the records, descriptors, and
52b8265621SJacob Kellercomponents are stored in linked lists.
53b8265621SJacob Keller
54b8265621SJacob KellerPerforming a flash update
55b8265621SJacob Keller=========================
56b8265621SJacob Keller
57b8265621SJacob KellerTo perform a flash update, the ``pldmfw`` module performs the following
58b8265621SJacob Kellersteps
59b8265621SJacob Keller
60b8265621SJacob Keller1. Parse the firmware file for record and component information
61b8265621SJacob Keller2. Scan through the records and determine if the device matches any record
62b8265621SJacob Keller   in the file. The first matched record will be used.
63b8265621SJacob Keller3. If the matching record provides package data, send this package data to
64b8265621SJacob Keller   the device.
65b8265621SJacob Keller4. For each component that the record indicates, send the component data to
66b8265621SJacob Keller   the device. For each component, the firmware may respond with an
67b8265621SJacob Keller   indication of whether the update is suitable or not. If any component is
68b8265621SJacob Keller   not suitable, the update is canceled.
69b8265621SJacob Keller5. For each component, send the binary data to the device firmware for
70b8265621SJacob Keller   updating.
71b8265621SJacob Keller6. After all components are programmed, perform any final device-specific
72b8265621SJacob Keller   actions to finalize the update.
73