| # 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.3.0 - Section 8. |
| |
| ## 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 |
| - ReferenceManifestLength: Supported, generated by the script |
| (PackageHeaderFormatVersion >= 4) |
| - 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 |
| - ReferenceManifestData: Supported (PackageHeaderFormatVersion >= 4), optional |
| field |
| - If specified in metadata file, must be provided as a hex string |
| - Example: "ReferenceManifestData": "0102030405060708090A0B0C0D0E0F10" |
| - If not specified, ReferenceManifestLength will be set to 0 |
| |
| ## Downstream 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: |
| |
| - DownstreamDeviceIDRecordCount: Supported, generated by the script |
| - DownstreamDeviceIDRecords: which is a list of Individual Downstream Device ID |
| Records. Each such record can have the following properties: |
| - DownstreamDeviceRecordLength: Supported, generated by the script |
| - DownstreamDeviceDescriptorCount: Supported, generated by the script |
| - DownstreamDeviceUpdateOptionFlags: Supported, must be specified in metadata |
| file |
| - add each bit that is to be set to 1 to the list |
| "DownstreamDeviceUpdateOptionFlags" |
| - DownstreamDeviceSelfContainedActivationMinVersionStringType: Supported - |
| only ASCII at the moment. Generated by the script |
| - DownstreamDeviceSelfContainedActivationMinVersionStringLength: Supported, |
| generated by the script |
| - DownstreamDevicePackageDataLength: Not supported. Set to 0 by the script |
| - DownstreamDeviceReferenceManifestLength: Supported, generated by the script |
| (PackageHeaderFormatVersion >= 4) |
| - DownstreamDeviceApplicableComponents: Supported, must be specified in |
| metadata file |
| - specify indexes of "ComponentImageInformationArea" values that apply in |
| the "DownstreamDeviceApplicableComponents" list |
| - DownstreamDeviceSelfContainedActivationMinVersionString: Supported, must be |
| specified in metadata file |
| - DownstreamDeviceSelfContainedActivationMinVersionComparisonStamp: Supported, |
| must be specified in metadata file |
| - DownstreamDeviceRecordDescriptors: 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 |
| - DownstreamDevicePackageData: Not supported at the moment |
| - DownstreamDeviceReferenceManifestData: Supported |
| (PackageHeaderFormatVersion >= 4), optional field |
| - If specified in metadata file, must be provided as a hex string |
| - Example: "DownstreamDeviceReferenceManifestData": |
| "AABBCCDDEEFF00112233445566778899" |
| - If not specified, DownstreamDeviceReferenceManifestLength will be set to 0 |
| |
| ## 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 |
| - ComponentOpaqueDataLength: Not supported at the moment. Set to 0 by the |
| script |
| - ComponentOpaqueData: Not supported at the moment |
| |
| ## Package Header Checksum |
| |
| Supported, generated by the script |
| |
| - Uses CRC-32 (IEEE 802.3 polynomial) algorithm |
| - Calculated over entire package header (excluding the checksum field itself) |
| |
| ## Package Payload Checksum |
| |
| Supported, generated by the script (PackageHeaderFormatVersion >= 4) |
| |
| - Uses CRC-32 (IEEE 802.3 polynomial) algorithm |
| - Calculated over all component images in the firmware package payload |
| - Continuous CRC32 calculation across all component images |
| - Compatible with C implementation (libpldm pldm_edac_crc32) |
