fw_info_bare.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef FW_INFO_BARE_H__
#define FW_INFO_BARE_H__
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
#include <string.h>
 
#define MAGIC_LEN_WORDS (CONFIG_FW_INFO_MAGIC_LEN / sizeof(uint32_t))
 
/* The supported offsets for the fw_info struct. */
#define FW_INFO_OFFSET0 0x0
#define FW_INFO_OFFSET1 0x200
#define FW_INFO_OFFSET2 0x400
#define FW_INFO_OFFSET3 0x800
#define FW_INFO_OFFSET4 0x1000
#define FW_INFO_OFFSET_COUNT 5
 
struct __packed fw_info_ext_api {
        /* Magic value to verify that the struct has the correct format.
         * The magic value will change whenever the format changes.
         */
        uint32_t magic[MAGIC_LEN_WORDS];
 
        /* The length of this header plus everything after this header. Must be
         * word-aligned.
         */
        uint32_t ext_api_len;
 
        /* The id of the EXT_API. */
        uint32_t ext_api_id;
 
        /* Flags specifying properties of the EXT_API. */
        uint32_t ext_api_flags;
 
        /* The version of this EXT_API. */
        uint32_t ext_api_version;
};
 
/* Check and provide a pointer to a fw_info_ext_api structure.
 *
 * @return pointer if valid, NULL if not.
 */
static inline const struct fw_info_ext_api *fw_info_ext_api_check(
                                                        uint32_t ext_api_addr)
{
        const struct fw_info_ext_api *ext_api;
        const uint32_t ext_api_magic[] = {EXT_API_MAGIC};
 
        ext_api = (const struct fw_info_ext_api *)(ext_api_addr);
        if (memcmp(ext_api->magic, ext_api_magic, CONFIG_FW_INFO_MAGIC_LEN)
                == 0) {
                return ext_api;
        }
        return NULL;
}
 
 
struct __packed fw_info_ext_api_request {
        /* The requested EXT_API. This struct defines the requested ID as well
         * as the minimum required version and the flags that must be set.
         */
        struct fw_info_ext_api request;
 
        /* The maximum accepted version. */
        uint32_t ext_api_max_version;
 
        /* This EXT_API is required. I.e. having this EXT_API available is a
         * hard requirement.
         */
        uint32_t required;
 
        /* Where to place a pointer to the EXT_API. */
        const struct fw_info_ext_api **ext_api;
};
 
 
struct __packed fw_info {
        /* Magic value to verify that the struct has the correct format.
         * The magic value will change whenever the format changes.
         */
        uint32_t magic[MAGIC_LEN_WORDS];
 
        /* Total size of this fw_info struct including the EXT_API lists. */
        uint32_t total_size;
 
        /* Size of the firmware image code. */
        uint32_t size;
 
        /* Monotonically increasing version counter.*/
        uint32_t version;
 
        /* The address of the start of the image. */
        uint32_t address;
 
        /* The address of the boot point (vector table) of the firmware. */
        uint32_t boot_address;
 
        /* Value that can be modified to invalidate the firmware. Has the value
         * CONFIG_FW_INFO_VALID_VAL when valid.
         */
        uint32_t valid;
 
        /* Reserved values (set to 0) */
        uint32_t reserved[4];
 
        /* The number of EXT_APIs in the @ref ext_apis list. */
        uint32_t ext_api_num;
 
        /* The number of EXT_API requests in the @ref ext_apis list. */
        uint32_t ext_api_request_num;
 
        /* A list of @ref ext_api_num EXT_APIs followed by @ref
         * ext_api_request_num EXT_API requests. Since the entries have
         * different lengths, the @ref ext_api_len of an entry is used to find
         * the next entry. To get to the EXT_API requests, first iterate over
         * all EXT_APIs.
         */
        const struct fw_info_ext_api ext_apis[];
};
 
/* Check and provide a pointer to a firmware_info structure.
 *
 * @return pointer if valid, NULL if not.
 */
static inline const struct fw_info *fw_info_check(uint32_t fw_info_addr)
{
        const struct fw_info *finfo;
        const uint32_t fw_info_magic[] = {FIRMWARE_INFO_MAGIC};
 
        finfo = (const struct fw_info *)(fw_info_addr);
        if (memcmp(finfo->magic, fw_info_magic, CONFIG_FW_INFO_MAGIC_LEN)
                == 0) {
                return finfo;
        }
        return NULL;
}
 
/* The actual fw_info struct offset accounting for any space in front of the
 * image, e.g. when there's a header.
 */
#define FW_INFO_CURRENT_OFFSET (CONFIG_FW_INFO_OFFSET + FW_INFO_VECTOR_OFFSET)
 
/* Array for run time usage. */
static const uint32_t fw_info_allowed_offsets[] = {
                                        FW_INFO_OFFSET0, FW_INFO_OFFSET1,
                                        FW_INFO_OFFSET2, FW_INFO_OFFSET3,
                                        FW_INFO_OFFSET4};
 
 
static inline const struct fw_info *fw_info_find(uint32_t firmware_address)
{
        const struct fw_info *finfo;
 
        for (uint32_t i = 0; i < FW_INFO_OFFSET_COUNT; i++) {
                finfo = fw_info_check(firmware_address +
                                                fw_info_allowed_offsets[i]);
                if (finfo) {
                        return finfo;
                }
        }
        return NULL;
}
 
typedef bool (*fw_info_ext_api_provide_t)(const struct fw_info *fwinfo,
                                        bool provide);
 
struct ext_api_provide_ext_api {
        fw_info_ext_api_provide_t ext_api_provide;
};
 
#ifdef __cplusplus
}
#endif
 
#endif /* FW_INFO_BARE_H__ */