README.md
1# Overview
2
3pldm_fwup_pkg_creator.py is a python script that can package one or more
4firmware image blobs into a PLDM firmware update package, as per the DSP0267
5specification v1.1.0 - Section 7.
6
7## Requirements
8
9- Python 3.6+
10- Python bitarray module
11 - For example on Ubuntu: sudo pip3 install bitarray
12
13## Usage
14
15 pldm_fwup_pkg_creator.py [-h]
16 pldmfwuppkgname metadatafile images
17 [images ...]
18
19 positional arguments:
20 pldmfwuppkgname Name of the PLDM FW update package
21 metadatafile Path of metadata JSON file
22 images One or more firmware image paths, in the same order as
23 ComponentImageInformationArea entries
24
25- Provide name for the PLDM FW update package, output will be written to a file
26 with this name
27- Providing the metadata JSON file is a must
28- The file path of at least one image file must be provided
29- In case there are more than one images, they should be specified in the _same
30 order_ as the entries in the "ComponentImageInformationArea" list in the
31 metadata json
32
33## Metadata JSON file
34
35Some fields corresponding to the PLDM firmware update package must be specified
36in an input metadata file (see the section 'Mapping fields to DSP0267') that's
37in JSON format. Typically it is not necessary to write this file each time the
38PLDM firmware update package has to be generated - one or more platform specific
39metadata JSON files can be reused. The key names used in the metadata JSON
40_match with the proprerty names_ used in DSP0267. There is an example metadata
41json file included - metadata-example.json, which has example entries for
42preparing a PLDM firmware update package that targets three devices, and there
43are a total of three component images.
44
45## Mapping fields to DSP0267
46
47This section describes the following:
48
49- which fields of the PLDM firmware update package are supported by the script
50- whether those fields need to be specified in the JSON, or are generated by the
51 script
52
53## Package Header Information
54
55Metadata JSON must have a key called "PackageHeaderInformation", which is of
56type Object. See below for details on properties:
57
58- PackageHeaderIdentifier: Supported, must be specified in metadata file
59- PackageHeaderFormatRevision: Supported, must be specified in metadata file
60- PackageHeaderSize: Supported, generated by the script
61- PackageReleaseDateTime: Supported, this is an optional field in the metadata
62 file and the format is YYYY-MM-DD HH:mm:ss (or with the space replaced with a
63 'T' for full ISO-8601 compliance). If not specified in the metadata file,
64 current time is taken.
65- ComponentBitmapBitLength: Supported, generated by the script
66 - Only 32 components supported at the moment
67- PackageVersionStringType: Supported - only ASCII at the moment. Generated by
68 the script
69- PackageVersionStringLength: Supported, generated by the script
70- PackageVersionString: Supported, must be specified in metadata file
71
72## Firmware Device Identification Area
73
74Metadata JSON must have a key called "FirmwareDeviceIdentificationArea", which
75is of type List. Each List entry corresponds to an firmware device ID record.
76See below for details on properties:
77
78- DeviceIDRecordCount: Supported, generated by the script
79- FirmwareDeviceIDRecords: which is a list of Individual Firmware Device ID
80 Records. Each such record can have the following properties:
81 - RecordLength: Supported, generated by the script
82 - DescriptorCount: Supported, generated by the script
83 - DeviceUpdateOptionFlags: Supported, must be specified in metadata file
84 - add each bit that is to be set to 1 to the list "DeviceUpdateOptionFlags"
85 - ComponentImageSetVersionStringType: Supported - only ASCII at the moment.
86 Generated by the script
87 - ComponentImageSetVersionStringLength: Supported, generated by the script
88 - FirmwareDevicePackageDataLength: Not supported. Set to 0 by the script
89 - ApplicableComponents: Supported, must be specified in metadata file
90 - specify indexes of "ComponentImageInformationArea" values that apply in
91 the "ApplicableComponents" list
92 - ComponentImageSetVersionString: Supported, must be specified in metadata
93 file
94 - RecordDescriptors: Metadata JSON must have a key called "Descriptors", which
95 is of type List. Each List entry corresponds to a descriptor. The first
96 entry is considered as the initial descriptor and the type shall be one of
97 the following 0x0000(PCI Vendor ID), 0x0001(IANA Enterprise ID),
98 0x0002(UUID), 0x0003(PnP Vendor ID), 0x0004(ACPI Vendor ID). The additional
99 descriptors support initial descriptor types and additionally 0x0100(PCI
100 Device ID), 0x0101(PCI Subsystem Vendor ID), 0x0102(PCI Subsystem ID),
101 0x0103(PCI Revision ID), 0x0104(PnP Product Identifier), 0x0105(ACPI Product
102 Identifier), 0xFFFF(Vendor defined). For descriptor types other than vendor
103 defined the properties expected are DescriptorType and DescriptorData. If
104 the descriptor type is vendor defined, the properties expected are
105 DescriptorType, VendorDefinedDescriptorTitleString and
106 VendorDefinedDescriptorData. See below for details on properties:
107 - DescriptorType: Supported, must be specified in metadata file
108 - DescriptorLength: Supported, generated by the script
109 - DescriptorData: Supported, must be specified in metadata file as a hex
110 string
111 - VendorDefinedDescriptorTitleStringType: Supported - only ASCII at the
112 moment.
113 - VendorDefinedDescriptorTitleStringLength: Supported, generated by the
114 script
115 - VendorDefinedDescriptorTitleString: Supported, must be specified in
116 metadata file
117 - VendorDefinedDescriptorData: Supported, must be specified in metadata file
118 as a hex string
119 - FirmwareDevicePackageData: Not supported at the moment
120
121## Downstream Device Identification Area
122
123Not supported at the moment
124
125## Component Image Information Area
126
127Metadata JSON must have a key called "ComponentImageInformationArea", which is
128of type List. Each List entry corresponds to an Individual Component Image
129Information. See below for details on properties:
130
131- ComponentImageCount: Supported, generated by the script
132- ComponentImageInformation: which is a list of Individual Component Image
133 Information records. Each such record can have the following properties:
134 - ComponentClassification: Supported, must be specified in metadata file
135 - ComponentIdentifier: Supported, must be specified in metadata file
136 - ComponentComparisonStamp: Supported. Must be specified as hexadecimal string
137 value in metadata file if ComponentOptions bit 1 is selected. If the
138 ComponentOptions bit 1 is not set, the ComponentComparisonStamp will be set
139 to the default value of 0xFFFFFFFF.
140 - ComponentOptions: Supported, must be specified in metadata file
141 - add each bit that is to be set to 1 to the list "ComponentOptions"
142 - supported options are Force Update and Use Component Comparison Stamp.
143 - RequestedComponentActivationMethod: Supported, must be specified in metadata
144 file
145 - add each bit that is to be set to 1 to the list
146 "RequestedComponentActivationMethod"
147 - ComponentLocationOffset: Supported, generated by the script
148 - ComponentSize: Supported, generated by the script
149 - ComponentVersionStringType: Supported - only ASCII at the moment. Generated
150 by the script
151 - ComponentVersionStringLength: Supported, generated by the script
152 - ComponentVersionString: Supported, must be specified in metadata file
153
154## Package Header Checksum
155
156Supported, generated by the script
157