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