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

   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.