Gecko Bootloader Customization Guidelines#

Customizing the Gecko Bootloader can require coordinated changes to the bootloader and application projects. This is especially important when you change the flash layout, security metadata, or reset handling.

Use the guidelines in this topic when you need to:

• Increase the flash space allocated to the Gecko Bootloader.

• Increase the number of application versions that application rollback protection can record.

• Add custom reset behavior without interrupting bootloader flash operations.

These changes affect memory that the bootloader, application, or both use. Before you make a change, define the complete flash layout and verify that all affected projects use consistent addresses and sizes. An inconsistent layout can cause overlapping flash regions, failed upgrades, invalid application images, or recovery problems.

Note: This topic applies to Gecko Bootloader projects for Series 2 devices using GSDK 4.0 or later. Configuration names, generated files, and default addresses can vary by device, bootloader type, and SDK release. Always use the files generated for your selected target as the starting point.

Plan the Flash Layout Before Customizing the Bootloader#

Before you change the bootloader configuration, define the complete flash layout for your product. Account for every flash region the device uses, including:

• Gecko Bootloader

• Application

• Bootloader upgrade location

• Internal storage slots or external storage layout

• Secure Engine upgrade staging area, if used

• NVM3 application storage

• Manufacturing tokens and key storage

• Application rollback-protection storage

Align the start address of each flash region to a flash-page boundary where required. Make sure that no regions overlap and that each region has enough space for its intended contents.

Avoid modifying SDK files directly. Instead, copy the SDK file into a project-owned location and modify the copy. This approach preserves your changes when you update the SDK and makes the customization easier to track.

A project-owned copy doesn't automatically receive changes made to the original SDK file in later releases. When you update the SDK, compare your copy with the updated SDK version and incorporate applicable changes.

Increase the Gecko Bootloader Size#

In some applications, the default Gecko Bootloader flash allocation may not be large enough. This can happen when additional bootloader functionality is enabled, and when custom bootloader code is added.

To increase the Gecko Bootloader size, move the application start address to a higher flash address and update the corresponding memory configuration in both the bootloader and application projects so that the flash regions do not overlap.

When increasing the Gecko Bootloader flash allocation, make the following coordinated changes:

Bootloader project: Determine the required bootloader size → update BTL_APPLICATION_BASE → update BTL_UPGRADE_LOCATION_BASE, if applicable → update LENGTH in the bootloader custom linker file.

Application project: Update FLASH ORIGIN → update the available FLASH LENGTH → configure the custom linker script.

Validate the complete flash layout: Check flash-page alignment → verify flash-region placement → confirm there is no unintended overlap.

The following subsections describe each of these changes in detail.

Required Changes in the Bootloader Project#

Update BTL_APPLICATION_BASE#

BTL_APPLICATION_BASE defines the first flash address available to the application. When the bootloader requires more flash space, move this address above the enlarged bootloader region.

The default macro is defined in:

<sdk-directory>/bootloader/platform/bootloader/api/btl_interface.h<sdk-directory>/bootloader/platform/bootloader/api/btl_interface.h

For EFR32xG21, main flash starts at 0x00000000 and uses 8 kB (0x2000) pages. The default application start address is:

#define BTL_APPLICATION_BASE (FLASH_BASE + 0x00004000UL)#define BTL_APPLICATION_BASE (FLASH_BASE + 0x00004000UL)

These values vary by device, bootloader configuration, and SDK release.

1. Build the bootloader with all required components and custom code.

2. Determine the required bootloader image size.

3. Add enough space for expected future growth.

4. Round the resulting reserved size up to the device flash-page size.

reserved_bootloader_size =
    round_up(required_bootloader_size, flash_page_size)

BTL_APPLICATION_BASE =
    FLASH_BASE + reserved_bootloader_sizereserved_bootloader_size =
    round_up(required_bootloader_size, flash_page_size)

BTL_APPLICATION_BASE =
    FLASH_BASE + reserved_bootloader_size

For example, reserve 32 kB for the bootloader:

reserved_bootloader_size = 32 kB = 0x8000reserved_bootloader_size = 32 kB = 0x8000

The new application start address is therefore:

#define BTL_APPLICATION_BASE (FLASH_BASE + 0x00008000UL)#define BTL_APPLICATION_BASE (FLASH_BASE + 0x00008000UL)

This change increases the reserved bootloader region from 0x4000 (16 kB) to 0x8000 (32 kB).

Update BTL_UPGRADE_LOCATION_BASE#

BTL_UPGRADE_LOCATION_BASE defines the temporary internal-flash location used to store a new bootloader image before the Secure Engine applies the upgrade.

When you select this location:

• Make sure that it is above BTL_APPLICATION_BASE

• Align it to the required flash-page boundary.

• Reserve enough contiguous flash for the complete bootloader upgrade image.

• Make sure the upgrade image doesn't overlap the application, storage, staging, or other reserved flash regions.

This value can be modified in the Bootloader Core component of the .slcp file.

For EFR32xG21, the default configuration is:

#define BTL_UPGRADE_LOCATION_BASE  0x8000UL
#define BTL_UPGRADE_LOCATION (FLASH_BASE + BTL_UPGRADE_LOCATION_BASE)#define BTL_UPGRADE_LOCATION_BASE  0x8000UL
#define BTL_UPGRADE_LOCATION (FLASH_BASE + BTL_UPGRADE_LOCATION_BASE)

If you move BTL_APPLICATION_BASE to 0x8000, you must also move BTL_UPGRADE_LOCATION_BASE to a higher address.

The selected location must meet the following requirements:

BTL_UPGRADE_LOCATION > BTL_APPLICATION_BASEBTL_UPGRADE_LOCATION > BTL_APPLICATION_BASE

BTL_UPGRADE_LOCATION must be aligned to the flash-page size

With a 32 kB bootloader region:

BTL_APPLICATION_BASE        = FLASH_BASE + 0x8000
BTL_UPGRADE_LOCATION_BASE   = 0x10000
BTL_UPGRADE_LOCATION        = FLASH_BASE + 0x10000BTL_APPLICATION_BASE        = FLASH_BASE + 0x8000
BTL_UPGRADE_LOCATION_BASE   = 0x10000
BTL_UPGRADE_LOCATION        = FLASH_BASE + 0x10000

The temporary bootloader upgrade image then occupies the following 32 kB range:

FLASH_BASE + 0x10000 to FLASH_BASE + 0x17FFFFLASH_BASE + 0x10000 to FLASH_BASE + 0x17FFF

The exact value depends on the flash layout of the target device and the required application, staging, and upgrade image sizes.

Update the Bootloader Linker Script#

Update the bootloader flash region LENGTH in the linker file to match the flash space allocated to the bootloader.

In Simplicity Studio 6, the autogenerated linker file is typically located at:

${workspace_loc:/${ProjName}}/autogen/linkerfile.ld${workspace_loc:/${ProjName}}/autogen/linkerfile.ld

Use this file as a reference and create a custom linker script for the project.

Configure a Custom Linker Script in a CMake Project#

Use the following procedure for both bootloader and application CMake projects.

1. Copy the autogenerated linker script to a project-owned location. For example:

<project-root>/linker/custom_linkerfile.ld<project-root>/linker/custom_linkerfile.ld

1. Make the required memory-region changes in the copied linker script. Do not modify the autogenerated file directly.

2. In the project’s top-level CMakeLists.txt, add the following code immediately after the include(<project_name>.cmake) line. This include creates the slc target and applies the default linker-script option.

3. Replace the autogenerated linker script provided by the slc target.

get_target_property(SLC_LINK_OPTIONS slc INTERFACE_LINK_OPTIONS)
if(SLC_LINK_OPTIONS STREQUAL "SLC_LINK_OPTIONS-NOTFOUND")
    set(SLC_LINK_OPTIONS)
endif()get_target_property(SLC_LINK_OPTIONS slc INTERFACE_LINK_OPTIONS)
if(SLC_LINK_OPTIONS STREQUAL "SLC_LINK_OPTIONS-NOTFOUND")
    set(SLC_LINK_OPTIONS)
endif()

1. Remove the autogenerated linker-script option:

list(FILTER SLC_LINK_OPTIONS EXCLUDE REGEX ".*/autogen/linkerfile\\.ld$")list(FILTER SLC_LINK_OPTIONS EXCLUDE REGEX ".*/autogen/linkerfile\\.ld$")

1. Add the project-owned custom linker script.

list(APPEND SLC_LINK_OPTIONS
    "-T${CMAKE_CURRENT_LIST_DIR}/linker/custom_linkerfile.ld"
)

set_property(TARGET slc PROPERTY INTERFACE_LINK_OPTIONS "${SLC_LINK_OPTIONS}")list(APPEND SLC_LINK_OPTIONS
    "-T${CMAKE_CURRENT_LIST_DIR}/linker/custom_linkerfile.ld"
)

set_property(TARGET slc PROPERTY INTERFACE_LINK_OPTIONS "${SLC_LINK_OPTIONS}")

1. Store the custom linker script and the CMakeLists.txt changes in source control.

Required Changes in the Application Project#

Update the Application Linker Script#

The application linker script must be updated so that the application starts at the new application base address.

In Simplicity Studio 6, the autogenerated linker file is typically located at:

${workspace_loc:/${ProjName}}/autogen/linkerfile.ld${workspace_loc:/${ProjName}}/autogen/linkerfile.ld

Use this file as a reference and create a custom linker script for the application project.

Update the flash region ORIGIN and LENGTH parameters.

For the example, the application region begins at:

FLASH (rx) : ORIGIN = <FLASH_BASE + 0x8000> , LENGTH = <reduced_application_length>FLASH (rx) : ORIGIN = <FLASH_BASE + 0x8000> , LENGTH = <reduced_application_length>

The ORIGIN parameter must be set to the first flash address available after the reserved bootloader region.

The LENGTH parameter must be reduced accordingly to account for the larger bootloader area.

After creating the custom linker file, update the application project settings to use the new linker script.

Flash Alignment Requirements#

Make sure the following values are page-aligned according to the flash page size of the target device:

• BTL_APPLICATION_BASE

• BTL_UPGRADE_LOCATION_BASE

• Application FLASH ORIGIN

The application and bootloader FLASH LENGTH values should be multiples of the flash page size so that the complete flash region boundaries remain page-aligned. Misaligned addresses can cause boot failures, erase/write failures, or upgrade image placement issues.

The required flash page size depends on the target device. Refer to the device Reference Manual or Datasheet for the correct flash page size.

Additional Memory Layout Considerations#

When increasing the bootloader size, make sure the complete flash layout still has enough space for all required regions, including:

• Bootloader

• Application

• Bootloader upgrade image slots

• Staging area

Increasing the bootloader region reduces the available space for the application and may also affect upgrade image storage. Review the full flash map before making the change.

Increasing Application Rollback-Protection Capacity#

When application rollback protection is enabled, the Gecko Bootloader records increasing application version values in flash at the end of the bootloader region. A new entry is consumed only when the application version increases. Installing another image with the same accepted version does not consume another entry.

The default implementation stores six increasing application versions. After all entries have been used, an image with a higher version is rejected until the bootloader is upgraded.

Note: Application rollback protection is not supported when the Secure Engine is configured to apply a full page lock that prevents the bootloader from writing the version storage area.

Calculate the Required Storage#

Each stored application version requires one 32-bit word. The implementation also uses two 32-bit metadata words. For a desired capacity of N increasing application versions, reserve:

rollback-protection storage = 4 * (N + 2) bytesrollback-protection storage = 4 * (N + 2) bytes

The default capacity is 6:

4 * (6 + 2) = 32 bytes = 0x20 bytes4 * (6 + 2) = 32 bytes = 0x20 bytes

For example, to store 20 increasing versions:

4 * (20 + 2) = 88 bytes = 0x58 bytes4 * (20 + 2) = 88 bytes = 0x58 bytes

Update the Software Capacity#

The default capacity is defined in:

platform/bootloader/core/btl_core_cfg.cplatform/bootloader/core/btl_core_cfg.c

The default definition is:

#define SL_GBL_APPLICATION_VERSION_STORAGE_CAPACITY 6UL#define SL_GBL_APPLICATION_VERSION_STORAGE_CAPACITY 6UL

Before modifying the SDK file, make a copy of btl_core_cfg.c, then change the SL_GBL_APPLICATION_VERSION_STORAGE_CAPACITY value to the required capacity. For example, for a capacity of 20:

#define SL_GBL_APPLICATION_VERSION_STORAGE_CAPACITY 20UL#define SL_GBL_APPLICATION_VERSION_STORAGE_CAPACITY 20UL

Reserve the Matching Flash Space#

The generated GCC linker file reserves 0x20 bytes for application rollback protection by default. In the generated file this is represented by a symbol similar to:

_app_rollback_protection_size = 0x20;_app_rollback_protection_size = 0x20;

In the custom bootloader linker file, change this value to the size calculated for the new capacity. For example, for a capacity of 20:

_app_rollback_protection_size = 0x58;_app_rollback_protection_size = 0x58;

The source capacity and linker reservation must always be changed together. If only the source value is increased, the bootloader code can overlap the version storage area. If only the linker reservation is increased, flash is reserved but the additional entries are not used.

Software Reset Considerations During Bootloader Operation#

The Gecko Bootloader uses software resets at defined transitions, such as entering firmware upgrade mode and starting a bootloader upgrade. These controlled resets include the reset reason and any state needed by the next stage. Custom code should not introduce asynchronous software resets while the bootloader is erasing or programming flash.

The safest reset boundary is a point at which no flash operation is active and the bootloader has completed or abandoned the current transaction.

Reset Guidance by Bootloader State#

The image parser withholds critical vector-table data until the image integrity and signature checks have completed. This prevents an incomplete standalone upgrade image from being interpreted as bootable. It does not preserve the previous application after application flash programming has started.

Use Controlled Reset Interfaces#

From the application, use bootloader_rebootAndInstall() to enter the bootloader and apply an image. This API writes the required bootloader command to shared RAM before issuing the software reset.

Inside custom bootloader code, use the bootloader reset interface and an appropriate reset reason instead of calling a generic system-reset function directly. For example, the internal reset interface provides reset_resetWithReason() for a non-returning reset with a bootloader reset cause.

Before issuing a reset, make sure that:

• The current flash erase or write operation has completed.

• Any DMA-based flash programming operation has completed.

• Storage drivers have completed pending transactions and have been shut down if required.

• The final status or reset reason has been committed.

• Custom callbacks are no longer using bootloader or storage state that will be lost on reset.

If custom code can request a reset from an interrupt, timer, communication callback, or watchdog handler, set a pending-reset flag and perform the reset later from a known safe point in the bootloader state machine.

Watchdog and Timeout Considerations#

Verification, flash erase, decompression, Delta DFU reconstruction, and Secure Engine operations can take longer than a normal boot path. Configure watchdog and communication timeouts for the worst-case duration of the selected device and image type.

Do not rely on a watchdog reset as the normal way to leave an upgrade operation. Service the watchdog at documented progress points, or use a watchdog configuration that permits the operation to complete while still detecting a stalled bootloader.

Test Reset and Power-Loss Recovery#

Test both software-reset and power-loss recovery at the boundaries of every flash-modifying operation. At minimum, cover:

• Before the first application page is erased

• During erase and programming of the first, middle, and last application pages

• Before and after image authentication completes

• During bootloader upgrade image staging

• Before the controlled reset into the Secure Engine or first-stage bootloader

• During application rollback-version storage updates

• During bootload-list updates for multiple storage slots

• During decompression or Delta DFU reconstruction, if supported

After each interruption, verify that the device never boots a partial or unauthenticated image, enters the expected recovery mode, and can complete a new upgrade attempt.