search

ARM-software / psa-firmware-update-spec

The PSA Firmware Update API specification, and discussion of future versions of this API.
Other
4 stars 2 forks source link

Image metadata and manifests #15

Open athoelke opened 2 years ago

athoelke commented 2 years ago

The v0.7 specification has a chapter (§6) on image metadata.

Analysis

§6.2 Usage models requires that image metadata must either be:

This appears to prohibit firmware image formats that embed the metadata in otherways, or wrap the firmware in a structured 'envelope' which provides the image metadata.

§6.1 Format profiles assumes that an Update Service might support SUIT, have a proprietary format, or support both.

This format is exposed as an Id, which is only present in the API as an attribute of an image staging area. An full example of SUIT-based metadata is provided.

Comparison

psa_fwu_set_manifest() is an optional API. TF-M currently does not support this API, and expects any metadata to be embedded within the firmware image.

Proposal

If the scope for v1.0 of the PSA Firmware Update API does not include support for SUIT (see #6), then there is no requirement to provide documentation relating to SUIT formats or concepts within the specification.

The constraint on how internal metadata is formatted seems to be unnecessary: for each Component, the Firmware Creator must construct Firmware Images that match the expectations of the Update Service. There does not seem to be value in reporting the expected format for the Component, or identifying the format of provided metadata.

As a result, we propose to reconsider the way that metadata is discussed and used within the specification and API.

Assumptions

  1. The v1.0 API must support both of the following use cases for metadata:

    1. The metadata for a firmware image is embedded within the image itself. The Update Service is able to parse the image and extract the metadata and firmware.
    2. The metadata for a firmware image is external to the image. This is supplied separately to the Update Service by the Client. The Update Service is able to parse the external metadata.

  2. Each Component in a system will either use embedded or external metadata. This is a design choice known to both the Firmware Creator and Update Service.

  3. The format of the metadata for a Component is a design choice known to both the Firmware Creator and Update Service.

API impact

There is no requirement to have the image and metadata format be part of the API itself. Firmware store information returned by psa_fwu_query() will not include the metadata format (see #9).

To support external metadata, the start operation (see #1) will accept an optional metadata/manifest parameter:

psa_status_t psa_fwu_start(psa_fwu_component_t id,
                           const void* metadata,
                           size_t metadata_size);

This replaces the separate psa_fwu_set_manifest() function.

Open issues

This API (and the one in v0.7) assumes that a manifest or metadata is 'not very big'. There is no mechanism to provide the metadata using multiple calls, in the same way that the firmware image can be provided incrementally using the psa_fwu_write() function.

This would be an issue if this API is used to pass a SUIT envelope, that embeds some or all of the firmware, rather than referring to external firmware files.

We propose to defer consideration for large manifests until after v1.0.