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