Description

Common bootloader interface defines and functions.

See bootloader-interface.h for source code.

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)

#define	BL_TYPE_APPLICATION (2)

#define	BL_TYPE_BOOTLOADER (3)

#define	BL_TYPE_SMALL_BOOTLOADER (4)

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.

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.

#define	BOOTLOADER_BASE_TYPE (extendedType) ((uint8_t)(((extendedType) >> 8U) & 0xFFU))
	Macro returning the base type of a bootloader when given an extended type.

#define	BOOTLOADER_MAKE_EXTENDED_TYPE (baseType, extendedSpecifier) ((uint16_t)(((uint16_t)baseType) << 8U) \| (((uint16_t)extendedSpecifier) & 0xFFU))
	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
	Macro defining the capabilities that this application has.

Function Documentation

◆ halBootloaderGetType()

BlBaseType halBootloaderGetType ( void )

Returns the bootloader base type the application was built for.

Returns: BL_TYPE_NULL , ::BL_TYPE_STANDALONE, or ::BL_TYPE_APPLICATION

◆ halBootloaderGetInstalledType()

BlExtendedType halBootloaderGetInstalledType ( void )

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

◆ halGetBootloaderVersion()

uint16_t halGetBootloaderVersion ( void )

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

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

◆ 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

`getEmberVersion`	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.
`customerVersion`	This will return the 32bit value specified in CUSTOMER_BOOTLOADER_VERSION at build time.

Macro Definition Documentation

◆ BL_TYPE_NULL

#define BL_TYPE_NULL (0)

Numerical definition for a bootloader type.

◆ BOOTLOADER_BASE_TYPE

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

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

◆ BOOTLOADER_MAKE_EXTENDED_TYPE

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

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

◆ BL_EXT_TYPE_NULL

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

Macro defining the extended NULL bootloader type.

◆ BL_EXT_TYPE_STANDALONE_UNKNOWN

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

Macro defining the extended standalone unknown bootloader type.

◆ BL_EXT_TYPE_SERIAL_UART

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

Macro defining the extended standalone UART bootloader type.

◆ BL_EXT_TYPE_SERIAL_UART_OTA

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

Macro defining the extended standalone OTA and UART bootloader type.

◆ BL_EXT_TYPE_SERIAL_USB

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

Macro defining the extended standalone USB bootloader type.

◆ BL_EXT_TYPE_SERIAL_USB_OTA

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

Macro defining the extended standalone OTA and USB bootloader type.

◆ BL_EXT_TYPE_APP_UNKNOWN

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

Macro defining the extended application unknown bootloader type.

◆ BL_EXT_TYPE_APP_SPI

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

Macro defining the extended application SPI bootloader type.

◆ BL_EXT_TYPE_APP_I2C

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

Macro defining the extended application I2C bootloader type.

◆ BL_EXT_TYPE_APP_LOCAL_STORAGE

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

Macro defining a type for the local storage app bootloader.

◆ BOOTLOADER_INVALID_VERSION

#define BOOTLOADER_INVALID_VERSION 0xFFFF

Define an invalid bootloader version.

◆ CUSTOMER_APPLICATION_VERSION

#define CUSTOMER_APPLICATION_VERSION 0

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

◆ CUSTOMER_APPLICATION_CAPABILITIES

#define CUSTOMER_APPLICATION_CAPABILITIES 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.

◆ CUSTOMER_APPLICATION_PRODUCT_ID

#define CUSTOMER_APPLICATION_PRODUCT_ID { 0 }

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

◆ MPSI_PLUGIN_SUPPORT

#define MPSI_PLUGIN_SUPPORT 0

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

◆ APPLICATION_PROPERTIES_CAPABILITIES_MPSI_SUPPORT_BIT

#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.

◆ 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.

Typedef Documentation

◆ BlBaseType

typedef uint8_t BlBaseType

Define the bootloader base type.

◆ BlExtendedType

typedef uint16_t BlExtendedType

Define the bootloader extended type.

Common Bootloader Legacy HAL