bl_interface.h

Go to the documentation of this file.

/* Copyright 2018 Wirepas Ltd. All Rights Reserved.
 *
 * See file LICENSE.txt for full license details.
 *
 */
 
#ifndef BL_INTERFACE_H_
#define BL_INTERFACE_H_
 
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
 
#if defined(EFR32_PLATFORM)
#include "em_cmu.h"
#endif
 
typedef enum
{
    BL_RES_OK            = 0,  
    BL_RES_ERROR         = 1,  
    BL_RES_BUSY          = 2,  
    BL_RES_NODRIVER      = 3,  
    BL_RES_PARAM         = 4,  
    BL_RES_INVALID_AREA  = 5,  
    BL_RES_TIMEOUT       = 6,  
    BL_RES_INVALID_STATE = 7,  
} bl_interface_res_e;
 
#define BL_MEMORY_AREA_UNDEFINED 0xFFFFFFFF
 
typedef uint32_t bl_memory_area_id_t;
 
typedef enum
{
    BL_MEM_AREA_TYPE_BOOTLOADER   = 0,  
    BL_MEM_AREA_TYPE_STACK        = 1,  
    BL_MEM_AREA_TYPE_APPLICATION  = 2,  
    BL_MEM_AREA_TYPE_PERSISTENT   = 3,  
    BL_MEM_AREA_TYPE_SCRATCHPAD   = 4,  
    BL_MEM_AREA_TYPE_USER         = 5,  
    BL_MEM_AREA_TYPE_MODEMFW      = 6,  
    BL_MEM_AREA_TYPE_MODEMDELTAFW = 7,  
} bl_memory_area_type_e;
 
typedef struct
{
    size_t flash_size;
    size_t write_page_size;
    size_t erase_sector_size;
    size_t write_alignment;
    uint32_t byte_write_time;
    uint32_t page_write_time;
    uint32_t sector_erase_time;
    uint32_t byte_write_call_time;
    uint32_t page_write_call_time;
    uint32_t sector_erase_call_time;
    uint32_t is_busy_call_time;
} bl_flash_info_t;
 
typedef struct
{
    bl_memory_area_id_t area_id;
    size_t area_size;
    uint32_t area_physical_address;
    bl_flash_info_t flash;
    bool external_flash;
    bool has_header;
    bl_memory_area_type_e type;
} bl_memory_area_info_t;
 
typedef struct
{
    uint32_t length;
    uint16_t crc;
    uint8_t seq;
    uint8_t major;
    uint8_t minor;
    uint8_t maint;
    uint8_t devel;
} bl_memory_area_header_t;
 
typedef enum
{
    BL_SCRAT_TYPE_BLANK = 0,
    BL_SCRAT_TYPE_PRESENT = 1,
    BL_SCRAT_TYPE_PROCESS = 2,
} bl_scrat_type_e;
 
typedef enum
{
    BL_SCRAT_WRITE_STATUS_OK = 0,
    BL_SCRAT_WRITE_STATUS_COMPLETED_OK = 1,
    BL_SCRAT_WRITE_STATUS_COMPLETED_ERROR = 2,
    BL_SCRAT_WRITE_STATUS_NOT_ONGOING = 3,
    BL_SCRAT_WRITE_STATUS_INVALID_START = 4,
    BL_SCRAT_WRITE_STATUS_INVALID_NUM_BYTES = 5,
    BL_SCRAT_WRITE_STATUS_INVALID_HEADER = 6,
    BL_SCRAT_WRITE_STATUS_INVALID_NULL_BYTES = 7,
    BL_SCRAT_WRITE_STATUS_FLASH_ERROR = 8,
} bl_scrat_write_status_e;
 
typedef enum
{
    BL_SCRAT_IS_UNKNOWN,
    BL_SCRAT_IS_CLEAR,
    BL_SCRAT_IS_NOTAG,
    BL_SCRAT_IS_INVALID_HEADER,
    BL_SCRAT_IS_INVALID_CRC,
    BL_SCRAT_IS_INVALID,
    BL_SCRAT_IS_VALID,
} bl_scrat_valid_e;
 
typedef enum
{
    BL_SCRAT_MODEM_FILE_TYPE_FULL_IMAGE = 0,
    BL_SCRAT_MODEM_FILE_TYPE_DELTA_IMAGE = 1,
    BL_SCRAT_MODEM_FILE_TYPE_INVALID = 255
} bl_scrat_modem_file_type_e;
 
typedef struct
{
    uint32_t area_length;
    uint32_t erase_time;
    uint32_t length;
    uint16_t crc;
    uint8_t seq;
    uint8_t flags;
    uint32_t type;
    uint32_t status;
    bool dedicated;
    bl_scrat_modem_file_type_e modem_fw_type;
    uint32_t modem_fw_data;
    uint32_t modem_fw_length;
} bl_scrat_info_t;
 
#if defined(NRF91_PLATFORM)
typedef struct
{
    const char * at_commands;
} bl_platform_nrf91_t;
#elif defined(NRF54_PLATFORM)
typedef struct
{
    const uint16_t hfxo_int_cap_ff;
 
    const uint16_t lfxo_int_cap_ff;
} bl_platform_nrf54_t;
#elif defined(EFR32_PLATFORM)
typedef struct
{
    const CMU_HFXOInit_TypeDef * hfxoInit;
    const CMU_LFXOInit_TypeDef * lfxoInit;
} bl_platform_efr32_t;
#endif
 
typedef union
{
#if defined(NRF52_PLATFORM)
    const void * nrf52;
#elif defined(NRF54_PLATFORM)
    const bl_platform_nrf54_t * nrf54;
#elif defined(NRF91_PLATFORM)
    const bl_platform_nrf91_t * nrf91;
#elif defined(EFR32_PLATFORM)
    const bl_platform_efr32_t * efr32;
#endif
} bl_platform_t;
 
typedef struct
{
    bool crystal_32k;
    bool dcdc;
    bl_platform_t platform;
} bl_hardware_capabilities_t;
 
typedef bl_interface_res_e (*bl_memory_area_startRead_f)(bl_memory_area_id_t id,
                                                         void *              to,
                                                         uint32_t from,
                                                         size_t   amount);
 
typedef bl_interface_res_e (*bl_memory_area_startWrite_f)(
    bl_memory_area_id_t id, uint32_t to, const void * from, size_t amount);
 
typedef bl_interface_res_e (*bl_memory_area_startErase_f)(
    bl_memory_area_id_t id, uint32_t * sector_base, size_t * number_of_sector);
 
typedef bool (*bl_memory_area_isBusy_f)(bl_memory_area_id_t id);
 
typedef bl_interface_res_e (*bl_memory_area_getAreaInfo_f)(
    bl_memory_area_id_t id, bl_memory_area_info_t * info);
 
typedef void (*bl_memory_area_getAreaList_f)(bl_memory_area_id_t * list,
                                             uint8_t *             num_areas);
 
typedef bl_interface_res_e (*bl_memory_area_getIdfromType_f)(
    bl_memory_area_id_t * id, bl_memory_area_type_e type);
 
typedef bl_interface_res_e (*bl_memory_area_getAreaHeader_f)(
    bl_memory_area_id_t id, bl_memory_area_header_t * header);
 
typedef uint8_t (*bl_memory_area_getMaxNumAreas_f)(void);
 
typedef bl_interface_res_e (*bl_scrat_getValidity_f)(
    bl_scrat_valid_e * validity);
 
typedef bl_interface_res_e (*bl_scrat_read_f)(void *   to,
                                              uint32_t from,
                                              size_t   amount);
 
typedef bl_interface_res_e (*bl_scrat_clear_f)(void (*clear_wdt)(void));
 
typedef bl_interface_res_e (*bl_scrat_begin_f)(uint32_t num_bytes,
                                               uint8_t  seq,
                                               void (*clear_wdt)(void));
 
typedef bl_interface_res_e (*bl_scrat_write_f)(
    uint32_t                  to,
    const void *              from,
    size_t                    amount,
    bl_scrat_write_status_e * status);
 
typedef bl_interface_res_e (*bl_scrat_getInfo_f)(bl_scrat_info_t * info);
 
typedef bl_interface_res_e (*bl_scrat_setBootable_f)(void);
 
typedef bl_interface_res_e (*bl_scrat_setStatus_f)(uint32_t status);
 
typedef const bl_hardware_capabilities_t * (*bl_hardware_getCapabilities_f)(
    void);
 
 
typedef struct
{
    bl_memory_area_startRead_f      startRead;
    bl_memory_area_startWrite_f     startWrite;
    bl_memory_area_startErase_f     startErase;
    bl_memory_area_isBusy_f         isBusy;
    bl_memory_area_getAreaInfo_f    getAreaInfo;
    bl_memory_area_getAreaList_f    getAreaList;
    bl_memory_area_getIdfromType_f  getIdfromType;
    bl_memory_area_getAreaHeader_f  getAreaHeader;
    bl_memory_area_getMaxNumAreas_f getMaxNumAreas;
} memory_area_services_t;
 
typedef struct
{
    bl_scrat_getValidity_f getValidity;
    bl_scrat_read_f        read;
    bl_scrat_clear_f       clear;
    bl_scrat_begin_f       begin;
    bl_scrat_write_f       write;
    bl_scrat_getInfo_f     getInfo;
    bl_scrat_setBootable_f setBootable;
    bl_scrat_setStatus_f   setStatus;
} scratchpad_services_t;
 
typedef struct
{
    bl_hardware_getCapabilities_f getCapabilities;
} hardware_services_t;
 
typedef struct
{
    uint32_t                       version;
    const memory_area_services_t * memory_area_services_p;
    const scratchpad_services_t *  scratchpad_services_p;
    const hardware_services_t *    hardware_services_p;
    const void *                   dflow_services_p;
} bl_interface_t;
 
#endif /* BL_INTERFACE_H_ */