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 dd/MM/yyyy HH:mm:ss. If not specified in the metadata 63 file, current time is taken. 64- ComponentBitmapBitLength: Supported, generated by the script 65 - Only 32 components supported at the moment 66- PackageVersionStringType: Supported - only ASCII at the moment. Generated by 67 the script 68- PackageVersionStringLength: Supported, generated by the script 69- PackageVersionString: Supported, must be specified in metadata file 70 71## Firmware Device Identification Area 72 73Metadata JSON must have a key called "FirmwareDeviceIdentificationArea", which 74is of type List. Each List entry corresponds to an firmware device ID record. 75See below for details on properties: 76 77- DeviceIDRecordCount: Supported, generated by the script 78- FirmwareDeviceIDRecords: which is a list of Individual Firmware Device ID 79 Records. Each such record can have the following properties: 80 - RecordLength: Supported, generated by the script 81 - DescriptorCount: Supported, generated by the script 82 - DeviceUpdateOptionFlags: Supported, must be specified in metadata file 83 - add each bit that is to be set to 1 to the list "DeviceUpdateOptionFlags" 84 - ComponentImageSetVersionStringType: Supported - only ASCII at the moment. 85 Generated by the script 86 - ComponentImageSetVersionStringLength: Supported, generated by the script 87 - FirmwareDevicePackageDataLength: Not supported. Set to 0 by the script 88 - ApplicableComponents: Supported, must be specified in metadata file 89 - specify indexes of "ComponentImageInformationArea" values that apply in 90 the "ApplicableComponents" list 91 - ComponentImageSetVersionString: Supported, must be specified in metadata 92 file 93 - RecordDescriptors: Metadata JSON must have a key called "Descriptors", which 94 is of type List. Each List entry corresponds to a descriptor. The first 95 entry is considered as the initial descriptor and the type shall be one of 96 the following 0x0000(PCI Vendor ID), 0x0001(IANA Enterprise ID), 97 0x0002(UUID), 0x0003(PnP Vendor ID), 0x0004(ACPI Vendor ID). The additional 98 descriptors support initial descriptor types and additionally 0x0100(PCI 99 Device ID), 0x0101(PCI Subsystem Vendor ID), 0x0102(PCI Subsystem ID), 100 0x0103(PCI Revision ID), 0x0104(PnP Product Identifier), 0x0105(ACPI Product 101 Identifier), 0xFFFF(Vendor defined). For descriptor types other than vendor 102 defined the properties expected are DescriptorType and DescriptorData. If 103 the descriptor type is vendor defined, the properties expected are 104 DescriptorType, VendorDefinedDescriptorTitleString and 105 VendorDefinedDescriptorData. See below for details on properties: 106 - DescriptorType: Supported, must be specified in metadata file 107 - DescriptorLength: Supported, generated by the script 108 - DescriptorData: Supported, must be specified in metadata file as a hex 109 string 110 - VendorDefinedDescriptorTitleStringType: Supported - only ASCII at the 111 moment. 112 - VendorDefinedDescriptorTitleStringLength: Supported, generated by the 113 script 114 - VendorDefinedDescriptorTitleString: Supported, must be specified in 115 metadata file 116 - VendorDefinedDescriptorData: Supported, must be specified in metadata file 117 as a hex string 118 - FirmwareDevicePackageData: Not supported at the moment 119 120## Downstream Device Identification Area 121 122Not supported at the moment 123 124## Component Image Information Area 125 126Metadata JSON must have a key called "ComponentImageInformationArea", which is 127of type List. Each List entry corresponds to an Individual Component Image 128Information. See below for details on properties: 129 130- ComponentImageCount: Supported, generated by the script 131- ComponentImageInformation: which is a list of Individual Component Image 132 Information records. Each such record can have the following properties: 133 - ComponentClassification: Supported, must be specified in metadata file 134 - ComponentIdentifier: Supported, must be specified in metadata file 135 - ComponentComparisonStamp: Supported. Must be specified as hexadecimal string 136 value in metadata file if ComponentOptions bit 1 is selected. If the 137 ComponentOptions bit 1 is not set, the ComponentComparisonStamp will be set 138 to the default value of 0xFFFFFFFF. 139 - ComponentOptions: Supported, must be specified in metadata file 140 - add each bit that is to be set to 1 to the list "ComponentOptions" 141 - supported options are Force Update and Use Component Comparison Stamp. 142 - RequestedComponentActivationMethod: Supported, must be specified in metadata 143 file 144 - add each bit that is to be set to 1 to the list 145 "RequestedComponentActivationMethod" 146 - ComponentLocationOffset: Supported, generated by the script 147 - ComponentSize: Supported, generated by the script 148 - ComponentVersionStringType: Supported - only ASCII at the moment. Generated 149 by the script 150 - ComponentVersionStringLength: Supported, generated by the script 151 - ComponentVersionString: Supported, must be specified in metadata file 152 153## Package Header Checksum 154 155Supported, generated by the script 156