1# Overview 2pldm_fwup_pkg_creator.py is a python script that can package one or more 3firmware image blobs into a PLDM firmware update package, as per the DSP0267 4specification v1.1.0 - Section 7. 5 6# Requirements 7- Python 3.6+ 8- Python bitarray module 9 - For example on Ubuntu: sudo pip3 install bitarray 10 11# Usage 12 13 pldm_fwup_pkg_creator.py [-h] 14 pldmfwuppkgname metadatafile images 15 [images ...] 16 17 positional arguments: 18 pldmfwuppkgname Name of the PLDM FW update package 19 metadatafile Path of metadata JSON file 20 images One or more firmware image paths, in the same order as 21 ComponentImageInformationArea entries 22 23- Provide name for the PLDM FW update package, output will be written to a file 24with this name 25- Providing the metadata JSON file is a must 26- The file path of at least one image file must be provided 27- In case there are more than one images, they should be specified in the 28*same order* as the entries in the "ComponentImageInformationArea" list in the 29metadata json 30 31# Metadata JSON file 32Some fields corresponding to the PLDM firmware update package must be 33specified in an input metadata file (see the section 'Mapping fields to 34DSP0267') that's in JSON format. Typically it is not necessary to write this 35file each time the PLDM firmware update package has to be generated - one or 36more platform specific metadata JSON files can be reused. The key names used in 37the metadata JSON *match with the proprerty names* used in DSP0267. 38There is an example metadata json file included - metadata-example.json, which 39has example entries for preparing a PLDM firmware update package that targets 40three devices, and there are a total of three component images. 41 42# Mapping fields to DSP0267 43This section describes the following: 44- which fields of the PLDM firmware update package are supported by the script 45- whether those fields need to be specified in the JSON, or are generated by the 46script 47 48## Package Header Information 49Metadata JSON must have a key called "PackageHeaderInformation", which is of 50type Object. See below for details on properties: 51- PackageHeaderIdentifier: Supported, must be specified in metadata file 52- PackageHeaderFormatRevision: Supported, must be specified in metadata file 53- PackageHeaderSize: Supported, generated by the script 54- PackageReleaseDateTime: Supported, this is an optional field in the metadata 55file and the format is dd/MM/yyyy HH:mm:ss. If not specified in the metadata 56file, current time is taken. 57- ComponentBitmapBitLength: Supported, generated by the script 58 - Only 32 components supported at the moment 59- PackageVersionStringType: Supported - only ASCII at the moment. Generated by 60the script 61- PackageVersionStringLength: Supported, generated by the script 62- PackageVersionString: Supported, must be specified in metadata file 63 64## Firmware Device Identification Area 65Metadata JSON must have a key called "FirmwareDeviceIdentificationArea", which 66is of type List. Each List entry corresponds to an firmware device ID record. 67See below for details on properties: 68- DeviceIDRecordCount: Supported, generated by the script 69- FirmwareDeviceIDRecords: which is a list of Individual Firmware Device ID 70Records. Each such record can have the following properties: 71 - RecordLength: Supported, generated by the script 72 - DescriptorCount: Supported, generated by the script 73 - DeviceUpdateOptionFlags: Supported, must be specified in metadata file 74 - add each bit that is to be set to 1 to the list 75 "DeviceUpdateOptionFlags" 76 - ComponentImageSetVersionStringType: Supported - only ASCII at the moment. 77 Generated by the script 78 - ComponentImageSetVersionStringLength: Supported, generated by the script 79 - FirmwareDevicePackageDataLength: Not supported. Set to 0 by the script 80 - ApplicableComponents: Supported, must be specified in metadata file 81 - specify all "ComponentIdentifier" values that apply in the 82 "ApplicableComponents" list 83 - ComponentImageSetVersionString: Supported, must be specified in metadata 84 file 85 - RecordDescriptors: 86 Metadata JSON must have a key called "Descriptors", which is of type List. 87 Each List entry corresponds to a descriptor. The first entry is considered 88 as the initial descriptor and the type shall be one of the following 89 0x0000(PCI Vendor ID), 0x0001(IANA Enterprise ID), 0x0002(UUID), 90 0x0003(PnP Vendor ID), 0x0004(ACPI Vendor ID). The additional 91 descriptors support initial descriptor types and additionally 92 0x0100(PCI Device ID), 0x0101(PCI Subsystem Vendor ID), 93 0x0102(PCI Subsystem ID), 0x0103(PCI Revision ID), 94 0x0104(PnP Product Identifier), 0x0105(ACPI Product Identifier), 95 0xFFFF(Vendor defined). For descriptor types other than vendor defined the 96 properties expected are DescriptorType and DescriptorData. If the descriptor 97 type is vendor defined, the properties expected are DescriptorType, 98 VendorDefinedDescriptorTitleString and VendorDefinedDescriptorData. 99 See below for details on properties: 100 - DescriptorType: Supported, must be specified in metadata file 101 - DescriptorLength: Supported, generated by the script 102 - DescriptorData: Supported, must be specified in metadata 103 file as a hex string 104 - VendorDefinedDescriptorTitleStringType: Supported - only ASCII at the 105 moment. 106 - VendorDefinedDescriptorTitleStringLength: Supported, generated by the 107 script 108 - VendorDefinedDescriptorTitleString: Supported, must be specified in 109 metadata file 110 - VendorDefinedDescriptorData: Supported, must be specified in metadata 111 file as a hex string 112 - FirmwareDevicePackageData: Not supported at the moment 113 114## Downstream Device Identification Area 115Not supported at the moment 116 117## Component Image Information Area 118Metadata JSON must have a key called "ComponentImageInformationArea", which 119is of type List. Each List entry corresponds to an Individual Component Image 120Information. See below for details on properties: 121- ComponentImageCount: Supported, generated by the script 122- ComponentImageInformation: which is a list of Individual Component Image 123Information records. Each such record can have the following properties: 124 - ComponentClassification: Supported, must be specified in metadata file 125 - ComponentIdentifier: Supported, must be specified in metadata file 126 - ComponentComparisonStamp: Not supported. Set to 0xFFFFFFFF by the script 127 - ComponentOptions: Supported, must be specified in metadata file 128 - add each bit that is to be set to 1 to the list "ComponentOptions" 129 - only supported option at the moment is Force Update (0x0) 130 - RequestedComponentActivationMethod: Supported, must be specified in 131 metadata file 132 - add each bit that is to be set to 1 to the list 133 "RequestedComponentActivationMethod" 134 - ComponentLocationOffset: Supported, generated by the script 135 - ComponentSize: Supported, generated by the script 136 - ComponentVersionStringType: Supported - only ASCII at the moment. 137 Generated by the script 138 - ComponentVersionStringLength: Supported, generated by the script 139 - ComponentVersionString: Supported, must be specified in metadata file 140 141## Package Header Checksum 142Supported, generated by the script 143