Example usage

Warning

These examples are for illustrative purposes only and are not guaranteed to compile. Many error codes are not handled in order to keep the examples brief. A real implementation will need to initialize variables appropriately and handle failures as they see fit.

Retrieve versions of installed images

#include <psa/update.h>
#include <stddef.h> /* not necessarily required */

void example_get_installation_info() {

    psa_status_t rc;
    psa_fwu_iterator_t iter;
    psa_image_id_t id;
    psa_image_info_t image_info;

    psa_fwu_get_image_id_iterator(&iter);

    do {
        psa_fwu_get_image_id(&iter, &id);

        rc = psa_fwu_query(id, &image_info);

        if (image_info.state == PSA_IMAGE_INSTALLED && rc == PSA_SUCCESS) {
            specific_protocol_report(image_info.image_id, image_info.version);
        }

    } while (psa_fwu_get_image_id_next());
}

Individual image update (single part operation)

A single image with no dependencies.

#include <psa/update.h>
#include <stddef.h> /* not necessarily required */

/* Single image update */
void example_install_single_image(void *image, size_t image_size, psa_image_id_t id) {
    
    psa_status_t rc;
    psa_image_id_t needed_image;
    psa_image_version_t needed_version;

    rc = psa_fwu_write(id, 0, image, image_size, &needed_image, &needed_version);
    rc = psa_fwu_install(id, &needed_image, &needed_version);

    if (rc == PSA_SUCCESS_REBOOT) {
        /* do other things and then eventually... */
        psa_fwu_request_reboot();
    } else {
        /* handle error */
    }
}

Invividual image update (multi part operation)

#include <psa/update.h>
#include <stddef.h> /* not necessarily required */

/* Single image update (multi-part) */
void example_install_single_image_multipart(size_t total_image_size, psa_image_id_t id) {

    psa_status_t rc;
    psa_image_id_t needed_image;
    psa_image_version_t needed_version;
    size_t offset = 0;
    size_t amount_to_send = PSA_FWU_MAX_BLOCK_SIZE;
    void *image;

    while (offset < total_image_size)
    {
        /* Unrealistic example, fetches malloc'd piece of image of size PSA_FWU_MAX_BLOCK_SIZE */
        image = fetch_next_part_of_image(id); 

        if ((total_image_size - offset) <= PSA_FWU_MAX_BLOCK_SIZE) {
            amount_to_send = total_image_size - offset;
        }

        rc = psa_fwu_write(id, offset, image[offset], amount_to_send, 
                            &needed_image, &needed_version);
        
        free(image);
        offset += amount_to_send;
    }

    rc = psa_fwu_install(id, &needed_image, &needed_version);

    if (rc == PSA_SUCCESS_REBOOT) {
        /* do other things and then eventually... */
        psa_fwu_request_reboot();
    } else if (rc == PSA_SUCCESS) {
        /* Success */
    } else {
        /* Handle error */
    }
}

Multiple dependent images (multi part operation)

#include <psa/update.h>
#include <stddef.h> /* not necessarily required */

void example_install_multiple_images(void *image, size_t image_size, psa_image_id_t id) {

    psa_fwu_ctx_t ctx;
    psa_status_t rc;
    psa_image_id_t needed_image;
    psa_image_version_t needed_version;
    size_t offset = 0;
    size_t amount_to_send = PSA_FWU_MAX_BLOCK_SIZE;
    void *image_part;

    while (offset < image_size)
    {
        if (image_size - offset) <= PSA_FWU_MAX_BLOCK_SIZE) {
            amount_to_send = (image_size - offset));

            rc = psa_fwu_write(id, offset, image[offset], amount_to_send, 
                               &needed_image, &needed_version);
            offset += amount_to_send;
        }

        rc = psa_fwu_install(id, &needed_image, &needed_version);

        if (rc == PSA_SUCCESS_DEPENDENCY_NEEDED) {
            /* Image might need download or might already been downloaded */
            int new_image_size = 0;
            void *new_image = retrieve_image_from_wherever(&needed_image, &needed_version,
                              &new_image_size);
            example_install_multiple_images(new_image, new_image_size, &needed_image);
        }

        if (rc == PSA_SUCCESS_REBOOT) {
            /* do other things and then eventually... */
            psa_fwu_request_reboot();
        } else if (rc == PSA_SUCCESS) {
            /* other success */
        } else {
            /* handle failures /*
        }
    }
}