1 .. SPDX-License-Identifier: GPL-2.0-only 1 .. SPDX-License-Identifier: GPL-2.0-only
2 2
3 ================================== 3 ==================================
4 PLDM Firmware Flash Update Library 4 PLDM Firmware Flash Update Library
5 ================================== 5 ==================================
6 6
7 ``pldmfw`` implements functionality for updati 7 ``pldmfw`` implements functionality for updating the flash on a device using
8 the PLDM for Firmware Update standard 8 the PLDM for Firmware Update standard
9 <https://www.dmtf.org/documents/pmci/pldm-firm 9 <https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>.
10 10
11 .. toctree:: 11 .. toctree::
12 :maxdepth: 1 12 :maxdepth: 1
13 13
14 file-format 14 file-format
15 driver-ops 15 driver-ops
16 16
17 ================================== 17 ==================================
18 Overview of the ``pldmfw`` library 18 Overview of the ``pldmfw`` library
19 ================================== 19 ==================================
20 20
21 The ``pldmfw`` library is intended to be used 21 The ``pldmfw`` library is intended to be used by device drivers for
22 implementing device flash update based on firm 22 implementing device flash update based on firmware files following the PLDM
23 firmware file format. 23 firmware file format.
24 24
25 It is implemented using an ops table that allo 25 It is implemented using an ops table that allows device drivers to provide
26 the underlying device specific functionality. 26 the underlying device specific functionality.
27 27
28 ``pldmfw`` implements logic to parse the packe 28 ``pldmfw`` implements logic to parse the packed binary format of the PLDM
29 firmware file into data structures, and then u 29 firmware file into data structures, and then uses the provided function
30 operations to determine if the firmware file i 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 31 so, it sends the record and component data to the firmware using the device
32 specific implementations provided by device dr 32 specific implementations provided by device drivers. Once the device
33 firmware indicates that the update may be perf 33 firmware indicates that the update may be performed, the firmware data is
34 sent to the device for programming. 34 sent to the device for programming.
35 35
36 Parsing the PLDM file 36 Parsing the PLDM file
37 ===================== 37 =====================
38 38
39 The PLDM file format uses packed binary data, 39 The PLDM file format uses packed binary data, with most multi-byte fields
40 stored in the Little Endian format. Several pi 40 stored in the Little Endian format. Several pieces of data are variable
41 length, including version strings and the numb 41 length, including version strings and the number of records and components.
42 Due to this, it is not straight forward to ind 42 Due to this, it is not straight forward to index the record, record
43 descriptors, or components. 43 descriptors, or components.
44 44
45 To avoid proliferating access to the packed bi 45 To avoid proliferating access to the packed binary data, the ``pldmfw``
46 library parses and extracts this data into sim 46 library parses and extracts this data into simpler structures for ease of
47 access. 47 access.
48 48
49 In order to safely process the firmware file, 49 In order to safely process the firmware file, care is taken to avoid
50 unaligned access of multi-byte fields, and to 50 unaligned access of multi-byte fields, and to properly convert from Little
51 Endian to CPU host format. Additionally the re 51 Endian to CPU host format. Additionally the records, descriptors, and
52 components are stored in linked lists. 52 components are stored in linked lists.
53 53
54 Performing a flash update 54 Performing a flash update
55 ========================= 55 =========================
56 56
57 To perform a flash update, the ``pldmfw`` modu 57 To perform a flash update, the ``pldmfw`` module performs the following
58 steps 58 steps
59 59
60 1. Parse the firmware file for record and comp 60 1. Parse the firmware file for record and component information
61 2. Scan through the records and determine if t 61 2. Scan through the records and determine if the device matches any record
62 in the file. The first matched record will 62 in the file. The first matched record will be used.
63 3. If the matching record provides package dat 63 3. If the matching record provides package data, send this package data to
64 the device. 64 the device.
65 4. For each component that the record indicate 65 4. For each component that the record indicates, send the component data to
66 the device. For each component, the firmwar 66 the device. For each component, the firmware may respond with an
67 indication of whether the update is suitabl 67 indication of whether the update is suitable or not. If any component is
68 not suitable, the update is canceled. 68 not suitable, the update is canceled.
69 5. For each component, send the binary data to 69 5. For each component, send the binary data to the device firmware for
70 updating. 70 updating.
71 6. After all components are programmed, perfor 71 6. After all components are programmed, perform any final device-specific
72 actions to finalize the update. 72 actions to finalize the update.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.