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