PSA Firmware Update API 0.7

Document number:	IHI 0093
Release Quality:	Beta
Issue Number:	0
Confidentiality:	Non-confidential
Date of Issue:	04/02/2021

Copyright © 2020-2021, Arm Limited. All rights reserved.

Abstract

This manual defines a standard firmware interface for installing firmware updates.

Note

This is a Beta quality release. The content is subject to change. Feedback should be sent to arm.psa-feedback@arm.com

Contents

• About this document
  • Release information
  • Arm Non-Confidential Document Licence (“Licence”)
  • References
  • Terms and abbreviations
  • Conventions
  • Feedback

• 1. Introduction
• 2. Design goals
  • 2.1. Suitable for constrained devices
  • 2.2. PSA Root of Trust update
  • 2.3. Application Root of Trust update
  • 2.4. Flexiblility for different trust models
  • 2.5. Protocol independence
  • 2.6. Transport independence
  • 2.7. Hardware flexibility
  • 2.8. Composite devices
  • 2.9. Room for different implementations
• 3. Terminology
  • 3.1. Image
  • 3.2. Trust anchor
  • 3.3. Installer
  • 3.4. Update client
  • 3.5. Secure Processing Environment (SPE)
  • 3.6. Staging area
• 4. Trust model and scenarios
• 5. Design overview
  • 5.1. Mandatory functions
    • 5.1.1. Querying installed images
    • 5.1.2. Image storing
    • 5.1.3. Metadata storage
    • 5.1.4. Verify image
    • 5.1.5. Triggering a reboot
  • 5.2. Optional functions
  • 5.3. State transitions for an image
  • 5.4. Dependencies
• 6. Image metadata
  • 6.1. Format profiles
  • 6.2. Usage models
  • 6.3. Example metadata
    • 6.3.1. Summary
    • 6.3.2. CBOR
• 7. API reference
  • 7.1. Library conventions
  • 7.2. Behavior on error
  • 7.3. Pointer conventions
  • 7.4. Macros
    • 7.4.1. Library versioning
    • 7.4.2. Image transfer
    • 7.4.3. Digest size
    • 7.4.4. Image states
    • 7.4.5. Image flags
  • 7.5. Types
    • 7.5.1. psa_image_version_t (struct)
    • 7.5.2. psa_staging_info_t (struct)
    • 7.5.3. psa_image_info_t (struct)
    • 7.5.4. psa_uuid_t (struct)
    • 7.5.5. psa_image_id_t (type)
    • 7.5.6. psa_fwu_iterator_t (type)
    • 7.5.7. psa_hash_t (struct)
  • 7.6. Status codes
    • 7.6.1. psa_status_t (type)
    • 7.6.2. PSA_SUCCESS (macro)
    • 7.6.3. PSA_SUCCESS_REBOOT (macro)
    • 7.6.4. PSA_SUCCESS_RESTART (macro)
    • 7.6.5. PSA_SUCCESS_DEPENDENCY_NEEDED (macro)
  • 7.7. Error codes
    • 7.7.1. PSA_ERROR_GENERIC_ERROR (macro)
    • 7.7.2. PSA_ERROR_NOT_SUPPORTED (macro)
    • 7.7.3. PSA_ERROR_NOT_PERMITTED (macro)
    • 7.7.4. PSA_ERROR_DOES_NOT_EXIST (macro)
    • 7.7.5. PSA_ERROR_INVALID_ARGUMENT (macro)
    • 7.7.6. PSA_ERROR_INSUFFICIENT_MEMORY (macro)
    • 7.7.7. PSA_ERROR_INSUFFICIENT_STORAGE (macro)
    • 7.7.8. PSA_ERROR_COMMUNICATION_FAILURE (macro)
    • 7.7.9. PSA_ERROR_STORAGE_FAILURE (macro)
    • 7.7.10. PSA_ERROR_DATA_CORRUPT (macro)
    • 7.7.11. PSA_ERROR_DATA_INVALID (macro)
    • 7.7.12. PSA_ERROR_HARDWARE_FAILURE (macro)
    • 7.7.13. PSA_ERROR_CORRUPTION_DETECTED (macro)
    • 7.7.14. PSA_ERROR_INVALID_SIGNATURE (macro)
    • 7.7.15. PSA_ERROR_INSUFFICIENT_DATA (macro)
    • 7.7.16. PSA_ERROR_WRONG_DEVICE (macro)
    • 7.7.17. PSA_ERROR_DEPENDENCY_NEEDED (macro)
    • 7.7.18. PSA_ERROR_CURRENTLY_INSTALLING (macro)
    • 7.7.19. PSA_ERROR_ALREADY_INSTALLED (macro)
    • 7.7.20. PSA_ERROR_INSTALL_INTERRUPTED (macro)
    • 7.7.21. PSA_ERROR_FLASH_ABUSE (macro)
    • 7.7.22. PSA_ERROR_INSUFFICIENT_POWER (macro)
    • 7.7.23. PSA_ERROR_DECRYPTION_FAILURE (macro)
    • 7.7.24. PSA_ERROR_MISSING_MANIFEST (macro)
  • 7.8. Functions
    • 7.8.1. psa_fwu_query (function)
    • 7.8.2. psa_fwu_set_manifest (function)
    • 7.8.3. psa_fwu_write (function)
    • 7.8.4. psa_fwu_install (function)
    • 7.8.5. psa_fwu_abort (function)
    • 7.8.6. psa_fwu_request_reboot (function)
    • 7.8.7. psa_fwu_request_rollback (function)
    • 7.8.8. psa_fwu_accept (function)
    • 7.8.9. psa_fwu_get_image_id_iterator (function)
    • 7.8.10. psa_fwu_get_image_id_next (function)
    • 7.8.11. psa_fwu_get_image_id_valid (function)
    • 7.8.12. psa_fwu_get_image_id (function)

• Example header file
  • psa/update.h
• Example usage
  • Retrieve versions of installed images
  • Individual image update (single part operation)
  • Invividual image update (multi part operation)
  • Multiple dependent images (multi part operation)
• Future changes
  • Rename psa_fwu_abort
  • Init function
• Change history