| # 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 |
