file-format.rst

  1.. SPDX-License-Identifier: GPL-2.0-only
  2
  3==================================
  4PLDM Firmware file format overview
  5==================================
  6
  7A PLDM firmware package is a binary file which contains a header that
  8describes the contents of the firmware package. This includes an initial
  9package header, one or more firmware records, and one or more components
 10describing the actual flash contents to program.
 11
 12This 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
 49Package Header
 50==============
 51
 52The package header begins with the UUID of the PLDM file format, and
 53contains information about the version of the format that the file uses. It
 54also includes the total header size, a release date, the size of the
 55component bitmap, and an overall package version.
 56
 57The 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
 74Device Records
 75==============
 76
 77The device firmware records area starts with a count indicating the total
 78number of records in the file, followed by each record. A single device
 79record describes what device matches this record. All valid PLDM firmware
 80files must contain at least one record, but optionally may contain more than
 81one record if they support multiple devices.
 82
 83Each record will identify the device it supports via TLVs that describe the
 84device, such as the PCI device and vendor information. It will also indicate
 85which set of components that are used by this device. It is possible that
 86only subset of provided components will be used by a given record. A record
 87may also optionally contain device-specific package data that will be used
 88by the device firmware during the update process.
 89
 90The 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
136Component Info
137==============
138
139The component information area begins with a count of the number of
140components. Following this count is a description for each component. The
141component information points to the location in the file where the component
142data is stored, and includes version data used to identify the version of
143the component.
144
145The 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
192Package Header CRC
193==================
194
195Following the component information is a short 4-byte CRC calculated over
196the contents of all of the header information.
197
198Component Images
199================
200
201The component images follow the package header information in the PLDM
202firmware file. Each of these is simply a binary chunk with its start and
203size defined by the matching component structure in the component info area.