Gitiles
Code Review Sign In
gerrit.openbmc.org / openbmc / pldm / 06f9b29e38f2090cfb69c370556f015abad48a02 / . / tools / fw-update
tree: 571f20bd72d16723ce1820db99c74e0856c7bf76 [path history] [tgz]
  1. metadata-example.json
  2. pldm_fwup_pkg_creator.py
  3. README.md
tools/fw-update/README.md

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