See Common for detailed documentation.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code. 

/***************************************************************************/
#ifndef __BOOTLOADER_INTERFACE_H__
#define __BOOTLOADER_INTERFACE_H__

#include "bootloader-interface-app.h"
#include "bootloader-interface-standalone.h"

#if defined(CORTEXM3_EFR32_MICRO) && !defined(NULL_BTL)
  #include "api/btl_interface.h"  // for ApplicationProperties_t and other
// Gecko bootloader related definitions.
#endif

#define BL_TYPE_NULL        (0)
#define BL_TYPE_STANDALONE  (1)
#define BL_TYPE_APPLICATION (2)
#define BL_TYPE_BOOTLOADER  (3)        // Generic bootloader type
#define BL_TYPE_SMALL_BOOTLOADER  (4)  // Generic, but small bootloader type

typedef uint8_t BlBaseType;

typedef uint16_t BlExtendedType;

#if defined(CORTEXM3_EFR32_MICRO) && !defined(NULL_BTL)
extern const ApplicationProperties_t appProperties;
#endif

BlBaseType halBootloaderGetType(void);

#define BOOTLOADER_BASE_TYPE(extendedType) \
  ((uint8_t)(((extendedType) >> 8U) & 0xFFU))

#define BOOTLOADER_MAKE_EXTENDED_TYPE(baseType, extendedSpecifier) \
  ((uint16_t)(((uint16_t)baseType) << 8U) | (((uint16_t)extendedSpecifier) & 0xFFU))

#define BL_EXT_TYPE_NULL                ((BL_TYPE_NULL << 8U) | 0x00U)

#define BL_EXT_TYPE_STANDALONE_UNKNOWN  ((BL_TYPE_STANDALONE << 8U) | 0x00U)

#define BL_EXT_TYPE_SERIAL_UART         ((BL_TYPE_STANDALONE << 8U) | 0x01U)

// skipping the extSpecifier of 0x02U in case we decide we want it to
//   be a bitmask for "OTA only"

#define BL_EXT_TYPE_SERIAL_UART_OTA     ((BL_TYPE_STANDALONE << 8U) | 0x03U)
#define BL_EXT_TYPE_EZSP_SPI            ((BL_TYPE_STANDALONE << 8U) | 0x04U)
#define BL_EXT_TYPE_EZSP_SPI_OTA        ((BL_TYPE_STANDALONE << 8U) | 0x06U)

#define BL_EXT_TYPE_SERIAL_USB         ((BL_TYPE_STANDALONE << 8U) | 0x07U)

#define BL_EXT_TYPE_SERIAL_USB_OTA     ((BL_TYPE_STANDALONE << 8U) | 0x08U)

#define BL_EXT_TYPE_APP_UNKNOWN         ((BL_TYPE_APPLICATION << 8U) | 0x00U)

#define BL_EXT_TYPE_APP_SPI             ((BL_TYPE_APPLICATION << 8U) | 0x01U)

#define BL_EXT_TYPE_APP_I2C             ((BL_TYPE_APPLICATION << 8U) | 0x02U)

#define BL_EXT_TYPE_APP_LOCAL_STORAGE   ((BL_TYPE_APPLICATION << 8U) | 0x03U)

BlExtendedType halBootloaderGetInstalledType(void);

#define BOOTLOADER_INVALID_VERSION 0xFFFF

uint16_t halGetBootloaderVersion(void);

void halGetExtendedBootloaderVersion(uint32_t* getEmberVersion, uint32_t* customerVersion);

#ifndef CUSTOMER_APPLICATION_VERSION
  #define CUSTOMER_APPLICATION_VERSION 0
#endif

#ifndef CUSTOMER_APPLICATION_CAPABILITIES
  #define CUSTOMER_APPLICATION_CAPABILITIES 0
#endif

#ifndef CUSTOMER_APPLICATION_PRODUCT_ID
  #define CUSTOMER_APPLICATION_PRODUCT_ID { 0 }
#endif

#ifdef EMBER_AF_PLUGIN_MPSI_SUPPORT
  #define MPSI_PLUGIN_SUPPORT 1
#else
  #define MPSI_PLUGIN_SUPPORT 0
#endif

#ifdef EMBER_AF_PLUGIN_DOTDOT_MFG_CERTS
extern uint8_t *longTokenAddress;
#endif

#define APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT 31

#define APPLICATION_PROPERTIES_CAPABILITIES                                     \
  (MPSI_PLUGIN_SUPPORT << APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT) \
  | (CUSTOMER_APPLICATION_CAPABILITIES & 0x7FFFFFFF)

#endif // __BOOTLOADER_INTERFACE_H__

Bootloader Numerical Definitions#

These are numerical definitions for the possible bootloader types and a typedef of the bootloader base type.

#define
BL_TYPE_NULL (0)

Numerical definition for a bootloader type.

#define
BL_TYPE_STANDALONE (1)

Numerical definition for a bootloader type.

#define
BL_TYPE_APPLICATION (2)

Numerical definition for a bootloader type.

#define
BL_TYPE_BOOTLOADER (3)

Numerical definition for a bootloader type.

#define
BL_TYPE_SMALL_BOOTLOADER (4)

Numerical definition for a bootloader type.

Bootloader type definitions#

These are the type definitions for the bootloader.

typedef uint8_t
BlBaseType

Define the bootloader base type.

typedef uint16_t
BlExtendedType

Define the bootloader extended type.

Macros#

#define
BOOTLOADER_BASE_TYPE (extendedType)

Macro returning the base type of a bootloader when given an extended type.

#define
BOOTLOADER_MAKE_EXTENDED_TYPE (baseType, extendedSpecifier)

Macro returning the extended type of a bootloader when given a base type and extendedSpecifier.

#define
BL_EXT_TYPE_NULL ((BL_TYPE_NULL << 8U) | 0x00U)

Macro defining the extended NULL bootloader type.

#define
BL_EXT_TYPE_STANDALONE_UNKNOWN ((BL_TYPE_STANDALONE << 8U) | 0x00U)

Macro defining the extended standalone unknown bootloader type.

#define
BL_EXT_TYPE_SERIAL_UART ((BL_TYPE_STANDALONE << 8U) | 0x01U)

Macro defining the extended standalone UART bootloader type.

#define
BL_EXT_TYPE_SERIAL_UART_OTA ((BL_TYPE_STANDALONE << 8U) | 0x03U)

Macro defining the extended standalone OTA and UART bootloader type.

#define
BL_EXT_TYPE_EZSP_SPI ((BL_TYPE_STANDALONE << 8U) | 0x04U)
#define
BL_EXT_TYPE_EZSP_SPI_OTA ((BL_TYPE_STANDALONE << 8U) | 0x06U)
#define
BL_EXT_TYPE_SERIAL_USB ((BL_TYPE_STANDALONE << 8U) | 0x07U)

Macro defining the extended standalone USB bootloader type.

#define
BL_EXT_TYPE_SERIAL_USB_OTA ((BL_TYPE_STANDALONE << 8U) | 0x08U)

Macro defining the extended standalone OTA and USB bootloader type.

#define
BL_EXT_TYPE_APP_UNKNOWN ((BL_TYPE_APPLICATION << 8U) | 0x00U)

Macro defining the extended application unknown bootloader type.

#define
BL_EXT_TYPE_APP_SPI ((BL_TYPE_APPLICATION << 8U) | 0x01U)

Macro defining the extended application SPI bootloader type.

#define
BL_EXT_TYPE_APP_I2C ((BL_TYPE_APPLICATION << 8U) | 0x02U)

Macro defining the extended application I2C bootloader type.

#define
BL_EXT_TYPE_APP_LOCAL_STORAGE ((BL_TYPE_APPLICATION << 8U) | 0x03U)

Macro defining a type for the local storage app bootloader.

#define
BOOTLOADER_INVALID_VERSION 0xFFFF

Define an invalid bootloader version.

#define
CUSTOMER_APPLICATION_VERSION 0

Macro defining the customer application version stored in the ApplicationProperties_t struct.

#define
CUSTOMER_APPLICATION_CAPABILITIES 0

Macro defining the customer application capabilities stored in the ApplicationProperties_t struct.

#define
CUSTOMER_APPLICATION_PRODUCT_ID { 0 }

Macro defining the customer application product ID stored in the ApplicationProperties_t struct.

#define
MPSI_PLUGIN_SUPPORT 0

Macro defining the support for the MPSI protocol stored in the capabilities field of the ApplicationProperties_t struct.

#define
APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT 31

Macro defining the bit position that corresponds to MPSI support in the capabilities field of the ApplicationProperties_t struct.

#define
APPLICATION_PROPERTIES_CAPABILITIES undefined

Macro defining the capabilities that this application has. This value is set in the capabilities field of the ApplicationProperties_t struct.

Functions#

BlBaseType
halBootloaderGetType(void)

Returns the bootloader base type the application was built for.

BlExtendedType
halBootloaderGetInstalledType(void)

Returns the extended bootloader type of the bootloader that is present on the chip.

uint16_t
halGetBootloaderVersion(void)

Returns the version of the installed bootloader, regardless of its type.

void
halGetExtendedBootloaderVersion(uint32_t *getEmberVersion, uint32_t *customerVersion)

Return extended bootloader version information, if supported. This API is not supported for EM2XX chips and only returns extra information on bootloaders built on or after the 4.7 release.

Bootloader Numerical Definitions Documentation#

BL_TYPE_NULL#

#define BL_TYPE_NULL
Value:
(0)

Numerical definition for a bootloader type.


Definition at line 43 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_TYPE_STANDALONE#

#define BL_TYPE_STANDALONE
Value:
(1)

Numerical definition for a bootloader type.


Definition at line 44 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_TYPE_APPLICATION#

#define BL_TYPE_APPLICATION
Value:
(2)

Numerical definition for a bootloader type.


Definition at line 45 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_TYPE_BOOTLOADER#

#define BL_TYPE_BOOTLOADER
Value:
(3)

Numerical definition for a bootloader type.


Definition at line 46 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_TYPE_SMALL_BOOTLOADER#

#define BL_TYPE_SMALL_BOOTLOADER
Value:
(4)

Numerical definition for a bootloader type.


Definition at line 47 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

Bootloader type definitions Documentation#

BlBaseType#

typedef uint8_t BlBaseType

Define the bootloader base type.


Definition at line 58 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BlExtendedType#

typedef uint16_t BlExtendedType

Define the bootloader extended type.


Definition at line 62 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

Macro Definition Documentation#

BOOTLOADER_BASE_TYPE#

#define BOOTLOADER_BASE_TYPE
Value:
(extendedType)

Macro returning the base type of a bootloader when given an extended type.


Definition at line 86 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BOOTLOADER_MAKE_EXTENDED_TYPE#

#define BOOTLOADER_MAKE_EXTENDED_TYPE
Value:
(baseType, extendedSpecifier)

Macro returning the extended type of a bootloader when given a base type and extendedSpecifier.


Definition at line 92 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_NULL#

#define BL_EXT_TYPE_NULL
Value:
((BL_TYPE_NULL << 8U) | 0x00U)

Macro defining the extended NULL bootloader type.


Definition at line 97 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_STANDALONE_UNKNOWN#

#define BL_EXT_TYPE_STANDALONE_UNKNOWN
Value:
((BL_TYPE_STANDALONE << 8U) | 0x00U)

Macro defining the extended standalone unknown bootloader type.


Definition at line 101 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_SERIAL_UART#

#define BL_EXT_TYPE_SERIAL_UART
Value:
((BL_TYPE_STANDALONE << 8U) | 0x01U)

Macro defining the extended standalone UART bootloader type.


Definition at line 105 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_SERIAL_UART_OTA#

#define BL_EXT_TYPE_SERIAL_UART_OTA
Value:
((BL_TYPE_STANDALONE << 8U) | 0x03U)

Macro defining the extended standalone OTA and UART bootloader type.


Definition at line 112 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_EZSP_SPI#

#define BL_EXT_TYPE_EZSP_SPI
Value:
((BL_TYPE_STANDALONE << 8U) | 0x04U)

Definition at line 113 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_EZSP_SPI_OTA#

#define BL_EXT_TYPE_EZSP_SPI_OTA
Value:
((BL_TYPE_STANDALONE << 8U) | 0x06U)

Definition at line 114 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_SERIAL_USB#

#define BL_EXT_TYPE_SERIAL_USB
Value:
((BL_TYPE_STANDALONE << 8U) | 0x07U)

Macro defining the extended standalone USB bootloader type.


Definition at line 118 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_SERIAL_USB_OTA#

#define BL_EXT_TYPE_SERIAL_USB_OTA
Value:
((BL_TYPE_STANDALONE << 8U) | 0x08U)

Macro defining the extended standalone OTA and USB bootloader type.


Definition at line 122 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_APP_UNKNOWN#

#define BL_EXT_TYPE_APP_UNKNOWN
Value:
((BL_TYPE_APPLICATION << 8U) | 0x00U)

Macro defining the extended application unknown bootloader type.


Definition at line 126 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_APP_SPI#

#define BL_EXT_TYPE_APP_SPI
Value:
((BL_TYPE_APPLICATION << 8U) | 0x01U)

Macro defining the extended application SPI bootloader type.


Definition at line 130 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_APP_I2C#

#define BL_EXT_TYPE_APP_I2C
Value:
((BL_TYPE_APPLICATION << 8U) | 0x02U)

Macro defining the extended application I2C bootloader type.


Definition at line 134 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BL_EXT_TYPE_APP_LOCAL_STORAGE#

#define BL_EXT_TYPE_APP_LOCAL_STORAGE
Value:
((BL_TYPE_APPLICATION << 8U) | 0x03U)

Macro defining a type for the local storage app bootloader.


Definition at line 138 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

BOOTLOADER_INVALID_VERSION#

#define BOOTLOADER_INVALID_VERSION
Value:
0xFFFF

Define an invalid bootloader version.


Definition at line 147 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

CUSTOMER_APPLICATION_VERSION#

#define CUSTOMER_APPLICATION_VERSION
Value:
0

Macro defining the customer application version stored in the ApplicationProperties_t struct.


Definition at line 173 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

CUSTOMER_APPLICATION_CAPABILITIES#

#define CUSTOMER_APPLICATION_CAPABILITIES
Value:
0

Macro defining the customer application capabilities stored in the ApplicationProperties_t struct.

Note

  • The capabilities field in the ApplicationProperties_t struct is shared with other values.


Definition at line 182 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

CUSTOMER_APPLICATION_PRODUCT_ID#

#define CUSTOMER_APPLICATION_PRODUCT_ID
Value:
{ 0 }

Macro defining the customer application product ID stored in the ApplicationProperties_t struct.


Definition at line 189 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

MPSI_PLUGIN_SUPPORT#

#define MPSI_PLUGIN_SUPPORT
Value:
0

Macro defining the support for the MPSI protocol stored in the capabilities field of the ApplicationProperties_t struct.


Definition at line 198 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT#

#define APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT
Value:
31

Macro defining the bit position that corresponds to MPSI support in the capabilities field of the ApplicationProperties_t struct.


Definition at line 212 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

APPLICATION_PROPERTIES_CAPABILITIES#

#define APPLICATION_PROPERTIES_CAPABILITIES
Value:
(MPSI_PLUGIN_SUPPORT << APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT) \
| (CUSTOMER_APPLICATION_CAPABILITIES & 0x7FFFFFFF)

Macro defining the capabilities that this application has. This value is set in the capabilities field of the ApplicationProperties_t struct.


Definition at line 218 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

Function Documentation#

halBootloaderGetType#

BlBaseType halBootloaderGetType (void )

Returns the bootloader base type the application was built for.

Parameters
N/A

Returns


Definition at line 81 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

halBootloaderGetInstalledType#

BlExtendedType halBootloaderGetInstalledType (void )

Returns the extended bootloader type of the bootloader that is present on the chip.

Parameters
N/A

Definition at line 143 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

halGetBootloaderVersion#

uint16_t halGetBootloaderVersion (void )

Returns the version of the installed bootloader, regardless of its type.

Parameters
N/A

Returns

  • Version if bootloader installed, or BOOTLOADER_INVALID_VERSION. A returned version of 0x1234U would indicate version 1.2 build 34


Definition at line 155 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h

halGetExtendedBootloaderVersion#

void halGetExtendedBootloaderVersion (uint32_t * getEmberVersion, uint32_t * customerVersion)

Return extended bootloader version information, if supported. This API is not supported for EM2XX chips and only returns extra information on bootloaders built on or after the 4.7 release.

Parameters
N/AgetEmberVersion

If specified, we will return the full 32bit ember version for this bootloader. Format is major, minor, patch, doc (4bit nibbles) followed by a 16bit build number.

N/AcustomerVersion

This will return the 32bit value specified in CUSTOMER_BOOTLOADER_VERSION at build time.


Definition at line 167 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/micro/bootloader-interface.h