E. Document change history

E.1. Changes between version 1.0 Beta and 1.0.0

General changes

• Clarified the definition of volatile staging and relaxed the requirements for non-volatile staging.

  • Defined the effects of the PSA_FWU_FLAG_VOLATILE_STAGING flag.

  • Permitted the volatility of the WRITING, FAILED, and UPDATED states to be implementation defined when the CANDIDATE state is not volatile.

  • Defined the impact on the state transitions when these states are volatile.

  • Added additional example state model diagrams for components with volatile staging.

  • See State model, Volatile states, and Variation in system design parameters.

• Added a Security Risk Assessment appendix for the Firmware Update API. See Security Risk Assessment.

API changes

• Added PSA_FWU_LOG2_WRITE_ALIGN, which the implementation uses to specify the required alignment of the data blocks written using psa_fwu_write().

E.2. Changes between version 0.7 and 1.0 Beta

General changes

• Relicensed the document under Attribution-ShareAlike 4.0 International with a patent license derived from Apache License 2.0. See License.

• Removed Profile IDs, and discussion of SUIT and manifest formats

• Revised and extended all of the early chapters covering the goals, architecture and design of the API.

• Updated code examples to match the v1.0 API. See Example usage.

API changes

• Renamed psa_image_id_t to psa_fwu_component_t, and changed the type to uint8_t.

• Renamed psa_image_info_t to psa_fwu_component_info_t.

  • Removed Image ID, Vendor ID and Class ID from psa_fwu_component_info_t structure.

  • Removed psa_fwu_staging_info_t, adding any important members directly to psa_fwu_component_info_t.

• Renamed psa_image_version_t to psa_fwu_image_version_t.

  • Resized the fields in psa_fwu_image_version_t to align with other project structures.

  • Added build field to psa_fwu_image_version_t.

• Reworked the state model to reflect the overall state of a firmware component, not a specific image.

  • Renamed PSA_FWU_UNDEFINED to PSA_FWU_READY - the default starting state for the state model.

  • Renamed CANDIDATE state to WRITING state. The new definition is PSA_FWU_WRITING.

  • Renamed REBOOT_NEEDED state to STAGED state. The new definition is PSA_FWU_STAGED.

  • Renamed PENDING_INSTALL state to TRIAL state. The new definition is PSA_FWU_TRIAL.

  • Renamed INSTALLED state to UPDATED state. The new definition is PSA_FWU_UPDATED.

  • Renamed REJECTED state to FAILED state. The new definition is PSA_FWU_FAILED.

  • Reintroduced REJECTED as a volatile state when rollback has been requested, but reboot has not yet occurred.

• Renamed some of the installation functions:

  • Rename psa_fwu_set_manifest() to psa_fwu_start(). This call is now mandatory, but the manifest data is optional.

  • Rename psa_fwu_request_rollback() to psa_fwu_reject(), to mirror psa_fwu_accept().

  • Rename psa_fwu_abort() to psa_fwu_clean().

• Explicit support for concurrent installation of multiple components:

  • Reintroduced CANDIDATE state for an image that has been prepared for installation, but not installed.

  • Add psa_fwu_finish() to mark a new firmware image as ready for installation.

  • Add psa_fwu_cancel() to abandon an update that is being prepared.

  • Removed the component_id parameter from psa_fwu_install(), psa_fwu_accept(), and psa_fwu_reject(): these now act atomically on all components in the initial state for the operation.

• Reference the standard definition of the status codes, and remove them from this specification. See Status codes.

  • Rationalize the API-specific error codes. This removes the following error codes:

    • PSA_ERROR_WRONG_DEVICE

    • PSA_ERROR_CURRENTLY_INSTALLING

    • PSA_ERROR_ALREADY_INSTALLED

    • PSA_ERROR_INSTALL_INTERRUPTED

    • PSA_ERROR_DECRYPTION_FAILURE

    • PSA_ERROR_MISSING_MANIFEST

  • Standardize the use of error codes, aligning with other PSA Certified APIs:

    • Use PSA_ERROR_BAD_STATE when operations are called in the wrong sequence.

    • Use PSA_ERROR_DOES_NOT_EXIST when operations are called with an unknown component Id.

    • Use PSA_ERROR_NOT_PERMITTED when firmware images do not comply with update policy.

• Removed the discovery API functions and types

  • psa_fwu_get_image_id_iterator()

  • psa_fwu_get_image_id_next()

  • psa_fwu_get_image_id_valid()

  • psa_fwu_get_image_id()

  • psa_fwu_iterator_t

• Removed Profile IDs, and discussion of SUIT and metadata formats

E.3. Changes between version 0.6 and 0.7

This section describes detailed changes between past versions.

• PSA_FWU_API_VERSION_MINOR has increased from 6 to 7

• psa_image_id_t is now defined as a 32-bit integer. Functions no longer have a pointer type for this parameter.

• UUID concept dropped from function names and parameters.

• Added Vendor ID and Class ID to psa_image_info_t structure.

• Added Future changes section

• Added error code and success code definitions

• Fixed mistake: psa_fwu_abort return type changed from void to psa_status_t

• Clarifications to the text

• Replaced PSA_ERROR_ROLLBACK_DETECTED with PSA_ERROR_NOT_PERMITTED

• Remove standardized image IDs until we get more feedback

• Improvements to the Design Overview text