5. Design overview
The document A Firmware Update Architecture for Internet of Things [SUIT-ARCH] describes an example flow and the expected device side actions:
Query image information
Validate image metadata
Store image
Verify image
Trigger reboot
The design of the interface offers functions for these actions. The interface contains three major classes of error codes: storage errors, security errors, and dependency errors. The caller must be prepared to handle these.
The interface is expected to be provided by an implementation that runs in the NSPE. However, it may be necessary to protect certain functions using the SPE on some platforms.
5.1. Mandatory functions
The interface supports these actions using the following calls.
5.1.1. Querying installed images
The caller calls psa_fwu_query
to fetch information about
firmware images on the device. This includes state for installed images, rejected images, and candidate images.
This information is expected to be passed to a remote operator or status tracker.
A local Update client may also use this information to make a local decision.
For example, the data may be used to avoid fetching images unnecessarily if they
are already on the device.
To satisfy Section 2.1, the query function uses an iterator to minimize memory footprint. The caller may relay this information to a remote status tracker. Eventually, new firmware is downloaded to the device by the caller.
Each image has its own local identifier that represents the type of image. This is known as an image ID. Queries are based on an image ID.
The image ID of each updatable image can be discovered using the provided iterator functions. The query function returns global identification information about the image, such as the associated Vendor ID, Class ID, and the hash of the public signing key.
5.1.2. Image storing
Each image has its own image ID that represents the type of image. Each image has its own staging area. The image ID is used by the implementation to determine the appropriate staging area.
The caller uses psa_fwu_write
to write a candidate image to its staging area.
To satisfy Section 2.1 the caller can use this operation to write an image
incrementally in blocks. On a rich device with plenty of memory, the caller uses this as a single-part function.
A number of errors can be detected and returned by this call, and can depend on the qualities of the implementation.
A staging area can be erased using psa_fwu_abort
.
5.1.3. Metadata storage
If the image does not embed metadata, then a standalone metadata object can be associated with the same image
by calling psa_fwu_set_manifest
with the same image ID.
5.1.4. Verify image
The caller finishes the firmware update process with psa_fwu_install
.
On success, the implementation checks any necessary preconditions and prepares installation.
On some implementations, this will starts an integrity check on the firmware image based on the metadata. On other implementations, the validation of the metadata is deferred to the bootloader when the platform next resets.
The implementation indicates whether a reboot is required to complete installation by using a return value.
The implementation indicates whether a dependency is missing by using a set of output parameters.
If a dependency is missing, the dependency is specified in two output parameters, the image ID of the missing image and the required version. The caller then fetches the required image and repeats the process.
5.1.5. Triggering a reboot
If a reboot is required to complete the firmware update process then the caller uses psa_fwu_request_reboot
to restart the platform. The
caller chooses when is an appropriate time to reboot the platform.
5.2. Optional functions
The following image management functions must be implemented if a PENDING_INSTALL state is supported:
A function,
psa_fwu_request_rollback
, is provided for application firmware to request the device to roll back the recently applied updates. This is for scenarios where the newly updated firmware detects a fatal problem with the update. The implementation may deny this request if this is prevented by security policy (e.g. rollback protection). An implementation can also choose not to support this.A function,
psa_fwu_accept
, is provided for application firmware to indicate whether the recently applied updates are working correctly. This is for scenarios where the newly installed firmware must be tested before it is permanently installed. An example of a test is a built in self-test.
5.3. State transitions for an image
The permitted state transitions are shown in the following diagram:
Every firmware update image begins in the CANDIDATE state. All successful firmware update images reach the INSTALLED state.
The state of an image can be queried using psa_fwu_query
.
5.4. Dependencies
An image can have a dependency on another image. When an image has a dependency it
cannot be installed until all of its dependencies are satisfied. This means that
all images must be written prior to calling psa_fwu_install
. Dependencies are
described within image metadata.
If a dependency is not explicit then the implementation is not guaranteed to detect compatibility issues. For instance, if an installation contains two images, A and B, and A depends on B, then the system will not be able to detect incompatibilities if B is upgraded in isolation. If mutual dependency is required, then A should specify a dependency on B and B should specify a dependency on A.
A dependency consists of an image ID and version.