# Overview
pldm_fwup_pkg_creator.py is a python script that can package one or more
firmware image blobs into a PLDM firmware update package, as per the DSP0267
specification v1.1.0 - Section 7.
# Requirements
- Python 3.6+
- Python bitarray module
- For example on Ubuntu: sudo pip3 install bitarray
# Usage
pldm_fwup_pkg_creator.py [-h]
pldmfwuppkgname metadatafile images
[images ...]
positional arguments:
pldmfwuppkgname Name of the PLDM FW update package
metadatafile Path of metadata JSON file
images One or more firmware image paths, in the same order as
ComponentImageInformationArea entries
- Provide name for the PLDM FW update package, output will be written to a file
with this name
- Providing the metadata JSON file is a must
- The file path of at least one image file must be provided
- In case there are more than one images, they should be specified in the _same
order_ as the entries in the "ComponentImageInformationArea" list in the
metadata json
# Metadata JSON file
Some fields corresponding to the PLDM firmware update package must be specified
in an input metadata file (see the section 'Mapping fields to DSP0267') that's
in JSON format. Typically it is not necessary to write this file each time the
PLDM firmware update package has to be generated - one or more platform specific
metadata JSON files can be reused. The key names used in the metadata JSON
_match with the proprerty names_ used in DSP0267. There is an example metadata
json file included - metadata-example.json, which has example entries for
preparing a PLDM firmware update package that targets three devices, and there
are a total of three component images.
# Mapping fields to DSP0267
This section describes the following:
- which fields of the PLDM firmware update package are supported by the script
- whether those fields need to be specified in the JSON, or are generated by the
script
## Package Header Information
Metadata JSON must have a key called "PackageHeaderInformation", which is of
type Object. See below for details on properties:
- PackageHeaderIdentifier: Supported, must be specified in metadata file
- PackageHeaderFormatRevision: Supported, must be specified in metadata file
- PackageHeaderSize: Supported, generated by the script
- PackageReleaseDateTime: Supported, this is an optional field in the metadata
file and the format is YYYY-MM-DD HH:mm:ss (or with the space replaced with a
'T' for full ISO-8601 compliance). If not specified in the metadata file,
current time is taken.
- ComponentBitmapBitLength: Supported, generated by the script
- Only 32 components supported at the moment
- PackageVersionStringType: Supported - only ASCII at the moment. Generated by
the script
- PackageVersionStringLength: Supported, generated by the script
- PackageVersionString: Supported, must be specified in metadata file
## Firmware Device Identification Area
Metadata JSON must have a key called "FirmwareDeviceIdentificationArea", which
is of type List. Each List entry corresponds to an firmware device ID record.
See below for details on properties:
- DeviceIDRecordCount: Supported, generated by the script
- FirmwareDeviceIDRecords: which is a list of Individual Firmware Device ID
Records. Each such record can have the following properties:
- RecordLength: Supported, generated by the script
- DescriptorCount: Supported, generated by the script
- DeviceUpdateOptionFlags: Supported, must be specified in metadata file
- add each bit that is to be set to 1 to the list "DeviceUpdateOptionFlags"
- ComponentImageSetVersionStringType: Supported - only ASCII at the moment.
Generated by the script
- ComponentImageSetVersionStringLength: Supported, generated by the script
- FirmwareDevicePackageDataLength: Not supported. Set to 0 by the script
- ApplicableComponents: Supported, must be specified in metadata file
- specify indexes of "ComponentImageInformationArea" values that apply in
the "ApplicableComponents" list
- ComponentImageSetVersionString: Supported, must be specified in metadata
file
- RecordDescriptors: Metadata JSON must have a key called "Descriptors", which
is of type List. Each List entry corresponds to a descriptor. The first
entry is considered as the initial descriptor and the type shall be one of
the following 0x0000(PCI Vendor ID), 0x0001(IANA Enterprise ID),
0x0002(UUID), 0x0003(PnP Vendor ID), 0x0004(ACPI Vendor ID). The additional
descriptors support initial descriptor types and additionally 0x0100(PCI
Device ID), 0x0101(PCI Subsystem Vendor ID), 0x0102(PCI Subsystem ID),
0x0103(PCI Revision ID), 0x0104(PnP Product Identifier), 0x0105(ACPI Product
Identifier), 0xFFFF(Vendor defined). For descriptor types other than vendor
defined the properties expected are DescriptorType and DescriptorData. If
the descriptor type is vendor defined, the properties expected are
DescriptorType, VendorDefinedDescriptorTitleString and
VendorDefinedDescriptorData. See below for details on properties:
- DescriptorType: Supported, must be specified in metadata file
- DescriptorLength: Supported, generated by the script
- DescriptorData: Supported, must be specified in metadata file as a hex
string
- VendorDefinedDescriptorTitleStringType: Supported - only ASCII at the
moment.
- VendorDefinedDescriptorTitleStringLength: Supported, generated by the
script
- VendorDefinedDescriptorTitleString: Supported, must be specified in
metadata file
- VendorDefinedDescriptorData: Supported, must be specified in metadata file
as a hex string
- FirmwareDevicePackageData: Not supported at the moment
## Downstream Device Identification Area
Not supported at the moment
## Component Image Information Area
Metadata JSON must have a key called "ComponentImageInformationArea", which is
of type List. Each List entry corresponds to an Individual Component Image
Information. See below for details on properties:
- ComponentImageCount: Supported, generated by the script
- ComponentImageInformation: which is a list of Individual Component Image
Information records. Each such record can have the following properties:
- ComponentClassification: Supported, must be specified in metadata file
- ComponentIdentifier: Supported, must be specified in metadata file
- ComponentComparisonStamp: Supported. Must be specified as hexadecimal string
value in metadata file if ComponentOptions bit 1 is selected. If the
ComponentOptions bit 1 is not set, the ComponentComparisonStamp will be set
to the default value of 0xFFFFFFFF.
- ComponentOptions: Supported, must be specified in metadata file
- add each bit that is to be set to 1 to the list "ComponentOptions"
- supported options are Force Update and Use Component Comparison Stamp.
- RequestedComponentActivationMethod: Supported, must be specified in metadata
file
- add each bit that is to be set to 1 to the list
"RequestedComponentActivationMethod"
- ComponentLocationOffset: Supported, generated by the script
- ComponentSize: Supported, generated by the script
- ComponentVersionStringType: Supported - only ASCII at the moment. Generated
by the script
- ComponentVersionStringLength: Supported, generated by the script
- ComponentVersionString: Supported, must be specified in metadata file
## Package Header Checksum
Supported, generated by the script