Skip to content

Commit b826562

Browse files
jacob-kellerdavem330
jacob-keller
authored and
davem330
committed
Add pldmfw library for PLDM firmware update
The pldmfw library is used to implement common logic needed to flash devices based on firmware files using the format described by the PLDM for Firmware Update standard. This library consists of logic to parse the PLDM file format from a firmware file object, as well as common logic for sending the relevant PLDM header data to the device firmware. A simple ops table is provided so that device drivers can implement device specific hardware interactions while keeping the common logic to the pldmfw library. This library will be used by the Intel ice networking driver as part of implementing device flash update via devlink. The library aims to be vendor and device agnostic. For this reason, it has been placed in lib/pldmfw, in the hopes that other devices which use the PLDM firmware file format may benefit from it in the future. However, do note that not all features defined in the PLDM standard have been implemented. Signed-off-by: Jacob Keller <[email protected]> Signed-off-by: David S. Miller <[email protected]>
1 parent 323410e commit b826562

File tree

11 files changed

+1630
-0
lines changed

11 files changed

+1630
-0
lines changed

‎Documentation/driver-api/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ available subsections can be seen below.
9595
phy/index
9696
pti_intel_mid
9797
pwm
98+
pldmfw/index
9899
rfkill
99100
serial/index
100101
sm501

‎Documentation/driver-api/pldmfw/driver-ops.rst

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
.. SPDX-License-Identifier: GPL-2.0-only
2+
3+
=========================
4+
Driver-specific callbacks
5+
=========================
6+
7+
The ``pldmfw`` module relies on the device driver for implementing device
8+
specific behavior using the following operations.
9+
10+
``.match_record``
11+
-----------------
12+
13+
The ``.match_record`` operation is used to determine whether a given PLDM
14+
record matches the device being updated. This requires comparing the record
15+
descriptors in the record with information from the device. Many record
16+
descriptors are defined by the PLDM standard, but it is also allowed for
17+
devices to implement their own descriptors.
18+
19+
The ``.match_record`` operation should return true if a given record matches
20+
the device.
21+
22+
``.send_package_data``
23+
----------------------
24+
25+
The ``.send_package_data`` operation is used to send the device-specific
26+
package data in a record to the device firmware. If the matching record
27+
provides package data, ``pldmfw`` will call the ``.send_package_data``
28+
function with a pointer to the package data and with the package data
29+
length. The device driver should send this data to firmware.
30+
31+
``.send_component_table``
32+
-------------------------
33+
34+
The ``.send_component_table`` operation is used to forward component
35+
information to the device. It is called once for each applicable component,
36+
that is, for each component indicated by the matching record. The
37+
device driver should send the component information to the device firmware,
38+
and wait for a response. The provided transfer flag indicates whether this
39+
is the first, last, or a middle component, and is expected to be forwarded
40+
to firmware as part of the component table information. The driver should an
41+
error in the case when the firmware indicates that the component cannot be
42+
updated, or return zero if the component can be updated.
43+
44+
``.flash_component``
45+
--------------------
46+
47+
The ``.flash_component`` operation is used to inform the device driver to
48+
flash a given component. The driver must perform any steps necessary to send
49+
the component data to the device.
50+
51+
``.finalize_update``
52+
--------------------
53+
54+
The ``.finalize_update`` operation is used by the ``pldmfw`` library in
55+
order to allow the device driver to perform any remaining device specific
56+
logic needed to finish the update.

‎Documentation/driver-api/pldmfw/file-format.rst

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
.. SPDX-License-Identifier: GPL-2.0-only
2+
3+
==================================
4+
PLDM Firmware file format overview
5+
==================================
6+
7+
A PLDM firmware package is a binary file which contains a header that
8+
describes the contents of the firmware package. This includes an initial
9+
package header, one or more firmware records, and one or more components
10+
describing the actual flash contents to program.
11+
12+
This diagram provides an overview of the file format::
13+
14+
overall file layout
15+
+----------------------+
16+
| |
17+
| Package Header |
18+
| |
19+
+----------------------+
20+
| |
21+
| Device Records |
22+
| |
23+
+----------------------+
24+
| |
25+
| Component Info |
26+
| |
27+
+----------------------+
28+
| |
29+
| Package Header CRC |
30+
| |
31+
+----------------------+
32+
| |
33+
| Component Image 1 |
34+
| |
35+
+----------------------+
36+
| |
37+
| Component Image 2 |
38+
| |
39+
+----------------------+
40+
| |
41+
| ... |
42+
| |
43+
+----------------------+
44+
| |
45+
| Component Image N |
46+
| |
47+
+----------------------+
48+
49+
Package Header
50+
==============
51+
52+
The package header begins with the UUID of the PLDM file format, and
53+
contains information about the version of the format that the file uses. It
54+
also includes the total header size, a release date, the size of the
55+
component bitmap, and an overall package version.
56+
57+
The following diagram provides an overview of the package header::
58+
59+
header layout
60+
+-------------------------+
61+
| PLDM UUID |
62+
+-------------------------+
63+
| Format Revision |
64+
+-------------------------+
65+
| Header Size |
66+
+-------------------------+
67+
| Release Date |
68+
+-------------------------+
69+
| Component Bitmap Length |
70+
+-------------------------+
71+
| Package Version Info |
72+
+-------------------------+
73+
74+
Device Records
75+
==============
76+
77+
The device firmware records area starts with a count indicating the total
78+
number of records in the file, followed by each record. A single device
79+
record describes what device matches this record. All valid PLDM firmware
80+
files must contain at least one record, but optionally may contain more than
81+
one record if they support multiple devices.
82+
83+
Each record will identify the device it supports via TLVs that describe the
84+
device, such as the PCI device and vendor information. It will also indicate
85+
which set of components that are used by this device. It is possible that
86+
only subset of provided components will be used by a given record. A record
87+
may also optionally contain device-specific package data that will be used
88+
by the device firmware during the update process.
89+
90+
The following diagram provides an overview of the device record area::
91+
92+
area layout
93+
+---------------+
94+
| |
95+
| Record Count |
96+
| |
97+
+---------------+
98+
| |
99+
| Record 1 |
100+
| |
101+
+---------------+
102+
| |
103+
| Record 2 |
104+
| |
105+
+---------------+
106+
| |
107+
| ... |
108+
| |
109+
+---------------+
110+
| |
111+
| Record N |
112+
| |
113+
+---------------+
114+
115+
record layout
116+
+-----------------------+
117+
| Record Length |
118+
+-----------------------+
119+
| Descriptor Count |
120+
+-----------------------+
121+
| Option Flags |
122+
+-----------------------+
123+
| Version Settings |
124+
+-----------------------+
125+
| Package Data Length |
126+
+-----------------------+
127+
| Applicable Components |
128+
+-----------------------+
129+
| Version String |
130+
+-----------------------+
131+
| Descriptor TLVs |
132+
+-----------------------+
133+
| Package Data |
134+
+-----------------------+
135+
136+
Component Info
137+
==============
138+
139+
The component information area begins with a count of the number of
140+
components. Following this count is a description for each component. The
141+
component information points to the location in the file where the component
142+
data is stored, and includes version data used to identify the version of
143+
the component.
144+
145+
The following diagram provides an overview of the component area::
146+
147+
area layout
148+
+-----------------+
149+
| |
150+
| Component Count |
151+
| |
152+
+-----------------+
153+
| |
154+
| Component 1 |
155+
| |
156+
+-----------------+
157+
| |
158+
| Component 2 |
159+
| |
160+
+-----------------+
161+
| |
162+
| ... |
163+
| |
164+
+-----------------+
165+
| |
166+
| Component N |
167+
| |
168+
+-----------------+
169+
170+
component layout
171+
+------------------------+
172+
| Classification |
173+
+------------------------+
174+
| Component Identifier |
175+
+------------------------+
176+
| Comparison Stamp |
177+
+------------------------+
178+
| Component Options |
179+
+------------------------+
180+
| Activation Method |
181+
+------------------------+
182+
| Location Offset |
183+
+------------------------+
184+
| Component Size |
185+
+------------------------+
186+
| Component Version Info |
187+
+------------------------+
188+
| Package Data |
189+
+------------------------+
190+
191+
192+
Package Header CRC
193+
==================
194+
195+
Following the component information is a short 4-byte CRC calculated over
196+
the contents of all of the header information.
197+
198+
Component Images
199+
================
200+
201+
The component images follow the package header information in the PLDM
202+
firmware file. Each of these is simply a binary chunk with its start and
203+
size defined by the matching component structure in the component info area.

‎Documentation/driver-api/pldmfw/index.rst

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
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.

‎MAINTAINERS

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13604,6 +13604,13 @@ S: Maintained
1360413604
F: Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml
1360513605
F: drivers/iio/chemical/pms7003.c
1360613606

13607+
PLDMFW LIBRARY
13608+
M: Jacob Keller <[email protected]>
13609+
S: Maintained
13610+
F: Documentation/driver-api/pldmfw/
13611+
F: include/linux/pldmfw.h
13612+
F: lib/pldmfw/
13613+
1360713614
PLX DMA DRIVER
1360813615
M: Logan Gunthorpe <[email protected]>
1360913616
S: Maintained

0 commit comments

Comments
 (0)