The API is defined in the C language. The API make use of standard C data types as defined in the ISO C99 specification.

7.1. Library conventions

Almost all functions return a status indication of type psa_status_t. This is an enumeration of integer values, with the value 0 (PSA_SUCCESS) or greater indicating successful operation and other values indicating errors.

Unless specified otherwise, if multiple error conditions apply, an implementation is free to return any of the applicable error codes. The choice of error code is considered an implementation quality issue. Different implementations can make different choices, for example to favor code size over ease of debugging or vice versa.

If the behavior is undefined, for example, if a function receives an invalid pointer as a parameter, this specification makes no guarantee that the function will return an error. Implementations are encouraged to return an error or halt the application in a manner that is appropriate for the platform if the undefined behavior condition can be detected. However, application developers need to be aware that undefined behavior conditions cannot be detected in general.

7.2. Behavior on error

All function calls must be implemented atomically:

When a function returns a type other than psa_status_t, the requested action has been carried out.
When a function returns the status PSA_SUCCESS or PSA_SUCCESS_xxx, the requested action has been carried out.
When a function returns another status of type psa_status_t, no action has been carried out. The content of the output parameters is undefined, but otherwise the state of the system has not changed, except as described below.

Unless otherwise documented, the content of output parameters is not defined when a function returns a status other than PSA_SUCCESS. It is recommended that implementations set output parameters to safe defaults to avoid limit risk, in case the caller does not properly handle all errors.

7.3. Pointer conventions

Unless explicitly stated in the documentation of a function, all pointers must be valid pointers to an object of the specified type.

7.4. Macros

7.4.1. Library versioning

`PSA_FWU_API_VERSION_MAJOR` (macro)

The major version of this implementation of the API.

#define PSA_FWU_API_VERSION_MAJOR 0

`PSA_FWU_API_VERSION_MINOR` (macro)

The minor version of this implementation of the API.

#define PSA_FWU_API_VERSION_MINOR 7

7.4.2. Image transfer

`PSA_FWU_MAX_BLOCK_SIZE` (macro)

The maximum permitted size for block in psa_fwu_write, in bytes. The specific value is implementation defined and must be greater than 0.

#define PSA_FWU_MAX_BLOCK_SIZE IMPDEF

Note

Implementations that aim to support post quantum security are recommended to provide a minimum of 4096, especially if there is an intention to support stateful hash-based signatures.

7.4.3. Digest size

`PSA_FWU_MAX_DIGEST_SIZE` (macro)

The maximum size of an image digest, in bytes. This is dependent on the hash algorithm used. The value is implementation defined.

#define PSA_FWU_MAX_DIGEST_SIZE IMPDEF

7.4.4. Image states

`PSA_IMAGE_UNDEFINED` (macro)

#define PSA_IMAGE_UNDEFINED 0

`PSA_IMAGE_CANDIDATE` (macro)

#define PSA_IMAGE_CANDIDATE 1

`PSA_IMAGE_INSTALLED` (macro)

#define PSA_IMAGE_INSTALLED 2

`PSA_IMAGE_REJECTED` (macro)

#define PSA_IMAGE_REJECTED 3

`PSA_IMAGE_PENDING_INSTALL` (macro)

#define PSA_IMAGE_PENDING_INSTALL 4

`PSA_IMAGE_REBOOT_NEEDED` (macro)

#define PSA_IMAGE_REBOOT_NEEDED 5

7.4.5. Image flags

`PSA_IMAGE_FLAG_VOLATILE_STAGING` (macro)

#define PSA_IMAGE_FLAG_VOLATILE_STAGING (0x00000001)

If set then image data written to the staging area will not maintained across a system reset.

If not set then image data written to the staging area is guaranteed to exist after a system reset.

`PSA_IMAGE_FLAG_ENCRYPTION` (macro)

#define PSA_IMAGE_FLAG_ENCRYPTION (0x00000002)

This flag describes whether an image is encrypted or not during an update.

If set then this type of image must be provided in encrypted form when installing.

If not set then this type of image must be provided in unencrypted form when installing.

7.5. Types

7.5.1. `psa_image_version_t` (struct)

Version information about an image

typedef struct psa_image_version_t {
    uint16_t major;
    uint16_t minor;
    uint16_t patch;
} psa_image_version_t;

Fields

major: The major version of an image.
minor: The minor version of an image. If the image has no minor version then this field is set to 0.
patch: The patch version of an image. If the image has no patch version then this field is set to 0.

7.5.2. `psa_staging_info_t` (struct)

A container with information about how to update the image.

typedef struct psa_staging_info_t {
    uint8_t flags;
    uint8_t metadata_format;
    size_t max_size;
    psa_hash_t key_id;
} psa_staging_info_t;

Fields

flags

A set of flags that describe extra information about the staging area. All unused flag values are reserved for future use by this specification and must be zero.

See PSA_IMAGE_FLAG_VOLATILE_STAGING (macro) for the flag values.

metadata_format

The expected format of the image’s signed metadata.

max_size

The maximum possible size of the image in bytes.

key_id

If PSA_IMAGE_FLAG_ENCRYPTION is set in flags then this field contains the key identifier. The key identifier is a cryptographic hash of the decryption key.

If PSA_IMAGE_FLAG_ENCRYPTION is not set in flags then this field must be zero.

7.5.3. `psa_image_info_t` (struct)

A container containing status information about an image.

typedef struct psa_image_info_t {
    struct psa_image_id_t image_id;
    psa_uuid_t vendor_id;
    psa_uuid_t class_id;
    struct psa_image_version_t version;
    uint8_t state;
    psa_staging_info_t staging;
    uint32_t error;
    uint8_t digest[PSA_FWU_MAX_DIGEST_SIZE];
} psa_image_info_t;

Fields

image_id

The assigned image ID.

vendor_id

The expected vendor ID from the image metadata.

class_id

The expected class ID from the image metadata.

version

The version of the image.

state

An integer that describes the current state of an image. Contains one of the following values:

PSA_IMAGE_UNDEFINED
PSA_IMAGE_CANDIDATE
PSA_IMAGE_INSTALLED
PSA_IMAGE_REJECTED
PSA_IMAGE_PENDING_INSTALL

Note

I think we want this information to be richer and extensible. For example, we could define a range of values defined by Arm and a range of values for implementers. For example. An implementation can provide extra information for debug reasons.

staging

A container with information about how to update the image.

error

An application-specific error that caused the firmware to roll back. If psa_fwu_request_rollback is not supported, then this field must be 0.

Note

What about error codes from bootloader? Are there use cases for a bootloader sending a dynamic amount of data?

digest

The digest of the image.

7.5.4. `psa_uuid_t` (struct)

A 128-bit universally unique identifier. UUIDs MUST be created according to A Universally Unique IDentifier (UUID) URN Namespace [RFC4122]. UUIDs should use versions 3, 4, or 5.

typedef struct psa_uuid_t {
    uint32_t uuid[4];
} psa_uuid_t;

Fields

uuid

7.5.5. `psa_image_id_t` (type)

A fixed size integer for the type of image that needs installing. This ID can be returned by a dependency error from psa_fwu_install. The caller must use the ID to download or locate the appropriate image to install.

typedef uint32_t psa_image_id_t;

7.5.6. `psa_fwu_iterator_t` (type)

An iterator object. Used with psa_fwu_query to iterate through all the image information.

The definition is implementation defined.

typedef /*...*/ psa_fwu_iterator_t;

7.5.7. `psa_hash_t` (struct)

A cryptographic hash.

struct psa_hash_t {
    uint8_t value[PSA_FWU_MAX_DIGEST_SIZE];
};

Fields

value

7.6. Status codes

7.6.1. `psa_status_t` (type)

Function return status.

typedef int32_t psa_status_t;

This is either PSA_SUCCESS, which is zero, indicating success; or a small negative value indicating that an error occurred. Errors are encoded as one of the PSA_ERROR_xxx values defined here.

7.6.2. `PSA_SUCCESS` (macro)

The action was completed successfully.

#define PSA_SUCCESS ((psa_status_t)0)

7.6.3. `PSA_SUCCESS_REBOOT` (macro)

The action was completed successfully and requires a system reboot to complete installation.

#define PSA_SUCCESS_REBOOT ((psa_status_t)+1)

7.6.4. `PSA_SUCCESS_RESTART` (macro)

The action was completed successfully and requires a restart of the component to complete installation.

#define PSA_SUCCESS_RESTART ((psa_status_t)+2)

7.6.5. `PSA_SUCCESS_DEPENDENCY_NEEDED` (macro)

The action was completed successfully and requires the installation of a dependency to complete installation.

#define PSA_SUCCESS_DEPENDENCY_NEEDED ((psa_status_t)+3)

7.7. Error codes

The following are the possible error codes that can be returned to the caller.

7.7.1. `PSA_ERROR_GENERIC_ERROR` (macro)

An error occurred that does not correspond to any defined failure cause.

#define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132)

Implementations can use this error code if none of the other standard error codes are applicable.

7.7.2. `PSA_ERROR_NOT_SUPPORTED` (macro)

The requested operation or a parameter is not supported by this implementation.

#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134)

If a combination of parameters is recognized and identified as not valid, return PSA_ERROR_INVALID_ARGUMENT instead.

7.7.3. `PSA_ERROR_NOT_PERMITTED` (macro)

The requested action is denied by a policy.

#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133)

It is recommended that implementations return this error code when the parameters are recognized as valid and supported, and a policy explicitly denies the requested operation.

If a subset of the parameters of a function call identify a forbidden operation, and another subset of the parameters are not valid or not supported, it is unspecified whether the function returns PSA_ERROR_NOT_PERMITTED, PSA_ERROR_NOT_SUPPORTED or PSA_ERROR_INVALID_ARGUMENT.

7.7.4. `PSA_ERROR_DOES_NOT_EXIST` (macro)

Asking for an item that doesn’t exist.

#define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140)

7.7.5. `PSA_ERROR_INVALID_ARGUMENT` (macro)

The parameters passed to the function are invalid.

#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135)

Implementations can return this error any time a parameter or combination of parameters are recognized as invalid.

7.7.6. `PSA_ERROR_INSUFFICIENT_MEMORY` (macro)

There is not enough runtime memory.

#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141)

If the action is carried out across multiple security realms, this error can refer to available memory in any of the security realms.

7.7.7. `PSA_ERROR_INSUFFICIENT_STORAGE` (macro)

There is not enough persistent storage.

#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142)

Functions that modify the key storage return this error code if there is insufficient storage space on the host media. In addition, many functions that do not otherwise access storage might return this error code if the implementation requires a mandatory log entry for the requested action and the log storage space is full.

7.7.8. `PSA_ERROR_COMMUNICATION_FAILURE` (macro)

There was a communication failure inside the implementation.

#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)

This can indicate a communication failure between the application and an external processor or between the processor and an external volatile or persistent memory. A communication failure can be transient or permanent depending on the cause.

Warning

If a function returns this error, it is undetermined whether the requested action has completed. Returning PSA_SUCCESS is recommended on successful completion whenever possible, however functions can return PSA_ERROR_COMMUNICATION_FAILURE if the requested action was completed successfully in an external processor but there was a breakdown of communication before the processor could report the status to the application.

7.7.9. `PSA_ERROR_STORAGE_FAILURE` (macro)

There was a storage failure that might have led to data loss.

#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146)

This error indicates that some persistent storage could not be read or written by the implementation. It does not indicate the following situations, which have specific error codes:

A corruption of volatile memory - use PSA_ERROR_CORRUPTION_DETECTED.
A communication error between the processor and its external storage - use PSA_ERROR_COMMUNICATION_FAILURE.
When the storage is in a valid state but is full - use PSA_ERROR_INSUFFICIENT_STORAGE.
When the storage or stored data is corrupted - use PSA_ERROR_DATA_CORRUPT.
When the stored data is not valid - use PSA_ERROR_DATA_INVALID.

A storage failure does not indicate that any data that was previously read is invalid. However this previously read data might no longer be readable from storage.

When a storage failure occurs, it is no longer possible to ensure the global integrity of the keystore. Depending on the global integrity guarantees offered by the implementation, access to other data might fail even if the data is still readable but its integrity cannot be guaranteed.

It is recommended to only use this error code to report a permanent storage corruption. However application writers must keep in mind that transient errors while reading the storage might be reported using this error code.

7.7.10. `PSA_ERROR_DATA_CORRUPT` (macro)

Stored data has been corrupted.

#define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152)

This error indicates that some persistent storage has suffered corruption. It does not indicate the following situations, which have specific error codes:

A corruption of volatile memory - use PSA_ERROR_CORRUPTION_DETECTED.
A communication error between the processor and its external storage - use PSA_ERROR_COMMUNICATION_FAILURE.
When the storage is in a valid state but is full - use PSA_ERROR_INSUFFICIENT_STORAGE.
When the storage fails for other reasons - use PSA_ERROR_STORAGE_FAILURE.
When the stored data is not valid - use PSA_ERROR_DATA_INVALID.

Note that a storage corruption does not indicate that any data that was previously read is invalid. However this previously read data might no longer be readable from storage.

When a storage failure occurs, it is no longer possible to ensure the global integrity of the keystore. Depending on the global integrity guarantees offered by the implementation, access to other data might fail even if the data is still readable but its integrity cannot be guaranteed.

It is recommended to only use this error code to report when a storage component indicates that the stored data is corrupt, or fails an integrity check.

7.7.11. `PSA_ERROR_DATA_INVALID` (macro)

Data read from storage is not valid for the implementation.

#define PSA_ERROR_DATA_INVALID ((psa_status_t)-153)

This error indicates that some data read from storage does not have a valid format. It does not indicate the following situations, which have specific error codes:

When the storage or stored data is corrupted - use PSA_ERROR_DATA_CORRUPT.
When the storage fails for other reasons - use PSA_ERROR_STORAGE_FAILURE.
An invalid argument to the API - use PSA_ERROR_INVALID_ARGUMENT.

This error is typically a result of an integration failure, where the implementation reading the data is not compatible with the implementation that stored the data.

It is recommended to only use this error code to report when data that is successfully read from storage is invalid.

7.7.12. `PSA_ERROR_HARDWARE_FAILURE` (macro)

A hardware failure was detected.

#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147)

A hardware failure can be transient or permanent depending on the cause.

7.7.13. `PSA_ERROR_CORRUPTION_DETECTED` (macro)

A tampering attempt was detected.

#define PSA_ERROR_CORRUPTION_DETECTED ((psa_status_t)-151)

If an application receives this error code, there is no guarantee that previously accessed or computed data was correct and remains confidential. In this situation, it is recommended that applications perform no further security functions and enter a safe failure state.

Implementations can return this error code if they detect an invalid state that cannot happen during normal operation and that indicates that the implementation’s security guarantees no longer hold. Depending on the implementation architecture and on its security and safety goals, the implementation might forcibly terminate the application.

This error indicates an attack against the application. Implementations must not return this error code as a consequence of the behavior of the application itself.

7.7.14. `PSA_ERROR_INVALID_SIGNATURE` (macro)

The signature, MAC or hash is incorrect.

#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149)

Verification functions return this error if the verification calculations completed successfully, and the value to be verified was determined to be incorrect.

If the value to verify has an invalid size, implementations can return either PSA_ERROR_INVALID_ARGUMENT or PSA_ERROR_INVALID_SIGNATURE.

7.7.15. `PSA_ERROR_INSUFFICIENT_DATA` (macro)

Return this error when there’s insufficient data when attempting to read from a resource.

#define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143)

7.7.16. `PSA_ERROR_WRONG_DEVICE` (macro)

#define PSA_ERROR_WRONG_DEVICE ((psa_status_t)-155)

7.7.17. `PSA_ERROR_DEPENDENCY_NEEDED` (macro)

#define PSA_ERROR_DEPENDENCY_NEEDED ((psa_status_t)-156)

7.7.18. `PSA_ERROR_CURRENTLY_INSTALLING` (macro)

#define PSA_ERROR_CURRENTLY_INSTALLING ((psa_status_t)-157)

7.7.19. `PSA_ERROR_ALREADY_INSTALLED` (macro)

#define PSA_ERROR_ALREADY_INSTALLED ((psa_status_t)-158)

7.7.20. `PSA_ERROR_INSTALL_INTERRUPTED` (macro)

#define PSA_ERROR_INSTALL_INTERRUPTED ((psa_status_t)-159)

7.7.21. `PSA_ERROR_FLASH_ABUSE` (macro)

#define PSA_ERROR_FLASH_ABUSE ((psa_status_t)-160)

7.7.22. `PSA_ERROR_INSUFFICIENT_POWER` (macro)

#define PSA_ERROR_INSUFFICIENT_POWER ((psa_status_t)-161)

7.7.23. `PSA_ERROR_DECRYPTION_FAILURE` (macro)

#define PSA_ERROR_DECRYPTION_FAILURE ((psa_status_t)-162)

7.7.24. `PSA_ERROR_MISSING_MANIFEST` (macro)

#define PSA_ERROR_MISSING_MANIFEST ((psa_status_t)-163)

7.8. Functions

7.8.1. `psa_fwu_query` (function)

Returns information for an image of a particular image ID.

psa_status_t psa_fwu_query(psa_image_id_t image_id,
                           psa_image_info_t *info);

Parameters

image_id: The image ID of the image to query.
info: Output parameter for image information related to the image ID.

Returns: psa_status_t

PSA_SUCCESS: Image information has been returned.
PSA_ERROR_NOT_PERMITTED: The caller is not authorized to access platform version information.

7.8.2. `psa_fwu_set_manifest` (function)

Stores a manifest object and associates it with a particular image ID.

This function is optional, and if not implemented shall return PSA_ERROR_NOT_SUPPORTED.

psa_status_t psa_fwu_set_manifest(psa_image_id_t image_id,
                                  const void *manifest,
                                  size_t manifest_size,
                                  psa_hash_t *manifest_dependency);

Parameters

image_id: The identifier of the image type.
manifest: A pointer to a buffer containing a manifest object.
manifest_size: The size of the manifest parameter.
manifest_dependency: Output parameter containing the hash of a required manifest when PSA_ERROR_DEPENDENCY_NEEDED is returned.

Returns: psa_status_t

PSA_SUCCESS: The manifest is persisted.
PSA_ERROR_NOT_PERMITTED: The manifest is too old to be installed. If the image metadata contains a timestamp, and it has expired, then this error is also returned.
PSA_ERROR_WRONG_DEVICE: The manifest is not intended for this device.
PSA_ERROR_INVALID_SIGNATURE: The manifest signature is not valid.
PSA_ERROR_DEPENDENCY_NEEDED: A different manifest is needed.
PSA_ERROR_INVALID_ARGUMENT: Parameter size is 0 or a pointer parameter is NULL.
PSA_ERROR_COMMUNICATION_FAILURE: The system could not communicate with the installer.
PSA_ERROR_NOT_SUPPORTED: This function is not implemented.
PSA_ERROR_CURRENTLY_INSTALLING: An existing manifest for image ID is currently being installed and is locked from writing. For example, psa_fwu_install is currently executing.
PSA_ERROR_GENERIC_ERROR: A fatal error occured.

Description

Note

Rationale

It is better to have a separate function for manifest related data rather than overload existing functions. Otherwise, we burden non-manifest users with configuring parameters correctly.

Similarly, if a system does not support a manifest, this function can not be supported using PSA_ERROR_NOT_SUPPORTED.

7.8.3. `psa_fwu_write` (function)

Writes an image to its staging area.

If the image size is less than or equal to PSA_FWU_MAX_BLOCK_SIZE, the caller can send the entire image in one call.

If the image size is greater than PSA_FWU_MAX_BLOCK_SIZE, the caller must send parts of the image by calling psa_fwu_write multiple times with different data blocks.

Once complete, the caller calls psa_fwu_install to install the candidate image.

psa_status_t psa_fwu_write(psa_image_id_t image_id,
                           size_t image_offset,
                           const void *block,
                           size_t block_size);

Parameters

image_id: The identifier of the image type.
image_offset: The offset of the image being passed into block, in bytes.
block: A buffer containing a block of image data. This might be a complete image or a subset.
block_size: Size of block. The size must not be greater than PSA_FWU_MAX_BLOCK_SIZE.

Returns: psa_status_t

PSA_SUCCESS

The data in block has been successfully stored.

PSA_ERROR_INVALID_ARGUMENT

One of the following error conditions occured:

The parameter size is greater than PSA_FWU_MAX_BLOCK_SIZE.

The parameter size is 0.

The combination of offset and size is out of bounds.

PSA_ERROR_INSUFFICIENT_MEMORY

There is not enough memory to process the update.

PSA_ERROR_INSUFFICIENT_STORAGE

There is not enough storage to process the update.

PSA_ERROR_COMMUNICATION_FAILURE

The system could not communicate with the installer.

PSA_ERROR_FLASH_ABUSE

The system is defending against quick flash exhaustion and is in a time-out period. The time-out period is implementation defined.

PSA_ERROR_DATA_CORRUPT

Data corruption has been detected. For example, an implementation that uses stream signatures may be able to detect corruption early.

PSA_ERROR_INSUFFICIENT_POWER

There is not enough power to complete the operation.

PSA_ERROR_GENERIC_ERROR

A fatal error occured.

PSA_ERROR_CURRENTLY_INSTALLING

The image is currently locked for writing. For example, psa_fwu_install is currently executing.

Description

It is the caller’s responsibility to account for how much data is written at which offset. If no persistent storage is directly available for the caller to perform accounting, then the caller can use a different storage mechanism, such as the PSA Storage API.

Note

Open point

Should we provide a mechanism to read firmware? For example psa_fwu_read?

7.8.4. `psa_fwu_install` (function)

Starts the installation of an image.

The authenticity and integrity of the image is checked during installation. If a reboot is required to complete installation then the implementation can choose to defer the authenticity checks to that point.

While this function executes, calls to psa_fwu_write with the image ID or a dependent image ID are rejected.

If an image dependency is missing then an error is returned.

Concurrent calls to this function with the same or dependent image IDs are not permitted and return an error.

psa_status_t psa_fwu_install(psa_image_id_t image_id,
                             psa_image_id_t *dependency_image_id,
                             psa_image_version_t *dependency_version);

Parameters

image_id: The identifier of the image to install.
dependency_image_id: If PSA_SUCCESS_DEPENDENCY_NEEDED is returned, this parameter is filled with dependency information.
dependency_version: If PSA_SUCCESS_DEPENDENCY_NEEDED is returned, this parameter is filled with the minimum required version for the dependency.

Returns: psa_status_t

PSA_SUCCESS: The image was successfully installed. The platform does not require a reboot.
PSA_SUCCESS_REBOOT: A system reboot is needed to finish installation. Use psa_fwu_request_reboot.
PSA_SUCCESS_RESTART: A restart of the updated component is required to complete the update. The restart mechanism is component specific.
PSA_SUCCESS_DEPENDENCY_NEEDED: Another image needs to be installed to finish installation. The caller must begin the firmware update process with the image specified in dependency.
PSA_ERROR_INVALID_SIGNATURE: The signature is incorrect.
PSA_ERROR_NOT_PERMITTED: The image is too old to be installed. If the image metadata contains a timestamp, and it has expired, then this error is also returned.
PSA_ERROR_DATA_CORRUPT: The image is corrupt.
PSA_ERROR_INSUFFICIENT_DATA: The image is smaller than expected.
PSA_ERROR_NOT_SUPPORTED: The image ID is either unknown or not supported.
PSA_ERROR_WRONG_DEVICE: The image is not intended for this device instance. For example, the image
PSA_ERROR_DEPENDENCY_NEEDED: A different image requires installation first.
PSA_ERROR_STORAGE_FAILURE: Some persistent storage could not be read or written by the implementation.
PSA_ERROR_MISSING_MANIFEST: A manifest is needed for this image ID. It must be set using psa_fwu_set_manifest.
PSA_ERROR_DECRYPTION_FAILURE: The key used to decrypt the data is unknown or decryption failed.
PSA_ERROR_INSUFFICIENT_POWER: There is not enough power to complete the operation.
PSA_ERROR_CURRENTLY_INSTALLING: The implementation is busy installing the requested image ID.
PSA_ERROR_ALREADY_INSTALLED: The storage item associated with image ID has already been installed.
PSA_ERROR_INSTALL_INTERRUPTED: Installation was interrupted or aborted.
PSA_ERROR_GENERIC_ERROR: A fatal error occured. This error is returned if not covered by other errors.

Description

7.8.5. `psa_fwu_abort` (function)

Aborts an ongoing installation and erases the staging area of the image.

psa_status_t psa_fwu_abort(psa_image_id_t image_id);

Parameters

image_id: The identifier of the image to abort installation.

Returns: psa_status_t

PSA_SUCCESS: Installation of the provided image ID has been aborted.
PSA_ERROR_INVALID_ARGUMENT: No image with the provided image ID is currently being installed.
PSA_ERROR_NOT_PERMITTED: The caller is not authorized to to abort an installation.
PSA_ERROR_STORAGE_FAILURE: Some persistent storage could not be erased.

7.8.6. `psa_fwu_request_reboot` (function)

Requests the platform to reboot. On success, the platform initiates a reboot, and might not return to the caller.

psa_status_t psa_fwu_request_reboot(void);

Returns: psa_status_t

PSA_SUCCESS: The platform will reboot soon.
PSA_ERROR_NOT_PERMITTED: The caller is not authorized to reboot the platform.

7.8.7. `psa_fwu_request_rollback` (function)

Requests the platform to roll back the firmware belonging to the caller and any other image that is dependent on that firmware. This is only used when the caller detects a fatal error after an update.

The platform may reject the request due to security policy.

psa_status_t psa_fwu_request_rollback(uint32_t error);

Parameters

error: An application-specific error code chosen by the application. If a specific error does not need to be reported, the value should be 0. On success, this error is recorded in the error field of the psa_image_info_t structure corresponding to this image.

Returns: psa_status_t

PSA_SUCCESS: The current firmware, and dependent images, will be rolled back on reboot.
PSA_ERROR_DOES_NOT_EXIST: The image ID is not recognized.
PSA_ERROR_NOT_PERMITTED: Either the caller is not authorized to roll back the platform or the current image cannot be rolled back due to security policy.
PSA_ERROR_NOT_SUPPORTED: This call is not implemented or rollback support is not implemented.

Description

On success, the current image becomes a rejected image, and the client will need to call psa_fwu_request_reboot to start the rollback process.

7.8.8. `psa_fwu_accept` (function)

Indicates to the implementation that the upgrade was successful. This changes the image state of a firmware image, and its dependencies, from PSA_IMAGE_PENDING_INSTALL to PSA_IMAGE_INSTALLED. For more information about image states, see the definition.

psa_status_t psa_fwu_accept(void);

Returns: psa_status_t

PSA_SUCCESS: The image and its dependencies have transitioned into a PSA_IMAGE_INSTALLED state.
PSA_ERROR_DOES_NOT_EXIST: The image ID is not recognized.
PSA_ERROR_NOT_SUPPORTED: The image ID is recognized but is not supported in this implementation.
PSA_ERROR_NOT_PERMITTED: The caller is not permitted to make this call.

Description

This function is optional and only required if an implementation supports a testing state.

If the image is in a PSA_IMAGE_PENDING_INSTALL state and this function is not called, then the image is replaced with an older image on reset.

7.8.9. `psa_fwu_get_image_id_iterator` (function)

Gets an iterator for use with psa_fwu_get_image_id. An iterator always returns at least one image ID.

void psa_fwu_get_image_id_iterator(psa_fwu_iterator_t *iterator);

Parameters

iterator

Returns: void

7.8.10. `psa_fwu_get_image_id_next` (function)

Advances an initialized iterator object. Used with psa_fwu_get_image_id.

bool psa_fwu_get_image_id_next(psa_fwu_iterator_t *iterator);

Parameters

iterator: An initialized iterator object.

Returns: bool

0: Returns 0 if there are no more images to report.
1: Returns 1 if there are more images to report.

Description

7.8.11. `psa_fwu_get_image_id_valid` (function)

Determines whether an iterator object is valid or not. Used with psa_fwu_get_image_id.

bool psa_fwu_get_image_id_valid(psa_fwu_iterator_t *iterator);

Parameters

iterator: An initialized iterator object

Returns: bool

0: Returns 0 if the iterator is invalid
1: Returns 1 if the iterator is valid.

7.8.12. `psa_fwu_get_image_id` (function)

Returns the image ID.

psa_status_t psa_fwu_get_image_id(psa_fwu_iterator_t *iterator,
                                  psa_image_id_t *image_id);

Parameters

iterator
image_id

Returns: psa_status_t

PSA_SUCCESS: Image information has been returned.
PSA_ERROR_INVALID_ARGUMENT: A parameter is not valid.
PSA_ERROR_NOT_PERMITTED: The caller is not authorized to access platform version information.

7.1. Library conventions

7.2. Behavior on error

7.3. Pointer conventions

7.4. Macros

7.4.1. Library versioning

PSA_FWU_API_VERSION_MAJOR (macro)

PSA_FWU_API_VERSION_MINOR (macro)

7.4.2. Image transfer

PSA_FWU_MAX_BLOCK_SIZE (macro)

7.4.3. Digest size

PSA_FWU_MAX_DIGEST_SIZE (macro)

7.4.4. Image states

PSA_IMAGE_UNDEFINED (macro)

PSA_IMAGE_CANDIDATE (macro)

PSA_IMAGE_INSTALLED (macro)

PSA_IMAGE_REJECTED (macro)

PSA_IMAGE_PENDING_INSTALL (macro)

PSA_IMAGE_REBOOT_NEEDED (macro)

7.4.5. Image flags

PSA_IMAGE_FLAG_VOLATILE_STAGING (macro)

PSA_IMAGE_FLAG_ENCRYPTION (macro)

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)

`PSA_FWU_API_VERSION_MAJOR` (macro)

`PSA_FWU_API_VERSION_MINOR` (macro)

`PSA_FWU_MAX_BLOCK_SIZE` (macro)

`PSA_FWU_MAX_DIGEST_SIZE` (macro)

`PSA_IMAGE_UNDEFINED` (macro)

`PSA_IMAGE_CANDIDATE` (macro)

`PSA_IMAGE_INSTALLED` (macro)

`PSA_IMAGE_REJECTED` (macro)

`PSA_IMAGE_PENDING_INSTALL` (macro)

`PSA_IMAGE_REBOOT_NEEDED` (macro)

`PSA_IMAGE_FLAG_VOLATILE_STAGING` (macro)

`PSA_IMAGE_FLAG_ENCRYPTION` (macro)

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.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.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.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)