Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dsyx/docs.silabs.com_zh/llms.txt

Use this file to discover all available pages before exploring further.

Silicon Labs Gecko Bootloader 是适用于所有较新 EFM32 和 EFR32 MCU 与无线 MCU 的通用 Bootloader。自 GSDK 4.0 起，Gecko Bootloader 重构为基于组件的架构，可在 Simplicity Studio 5 的 Project Configurator 中直观地安装和配置各个组件，生成适配不同协议栈和升级场景的 Bootloader 映像。

​
概述与架构

Gecko Bootloader 的主要特性：

通用性

适用于 Silicon Labs Gecko 系列 MCU 和无线 MCU，支持 EFM32 和 EFR32 Series 1 及 Series 2 设备。

可现场升级

Bootloader 自身可现场更新，支持添加新功能、更改通信协议和修复安全漏洞。

安全特性

内置 Secure Boot（每次引导验证签名）、已签名升级映像文件和已加密升级映像文件支持。

GBL 文件格式

使用专有 GBL（Gecko Bootloader）文件格式，扩展名 .gbl，支持 Application、Bootloader 和 SE 升级内容的组合打包。

​
Series 1 vs Series 2 架构差异

在 Series 1 设备上，Gecko Bootloader 采用两阶段（Two-Stage）设计，包含 First Stage Bootloader 和 Main Stage Bootloader。First Stage 通过 CRC32 校验和验证 Main Bootloader 更新映像的完整性，完成 Main Bootloader 的现场升级。 在 Series 2 设备上，Gecko Bootloader 仅包含 Main Stage Bootloader，First Stage Bootloader 的角色由 Secure Engine（SE）承担。SE 可以是硬件实现（HSE）或虚拟实现（VSE）。

​
GBL 文件格式

GBL 文件是 Gecko Bootloader 专用的升级映像格式，由多个带标签（Tag）的数据块组成。

​
明文 GBL 标签结构

一个典型的 GBL 文件 Tag 序列如下所示： 
GBL Header Tag
GBL Application Tag（可选，含 Application 映像）
GBL Bootloader Tag（可选，含 Bootloader 升级映像）
GBL SE Upgrade Tag（可选，含 SE 升级映像）
GBL End Tag

​
加密 GBL 标签结构

启用加密后，内容被包裹在加密 Tag 中： 
GBL Header Tag
GBL Encryption Init Tag
GBL Encryption Data Tag（含加密的 Application/Bootloader/SE 内容）
GBL End Tag
可以使用 Simplicity Commander 将多种内容组合为单个升级映像：
commander gbl create myupgrade.gbl \
  --app myapp.s37 \
  --bootloader mybootloader.s37 \
  --seupgrade mySecureElement.seu

​
Bootloader 运行模式

​
Standalone Bootloader 操作流程

1

应用程序请求重启

应用程序通过共享内存或 API 向 Bootloader 发出重启请求，设备进入 Bootloader 模式。
2

下载 GBL 升级文件

Bootloader 通过配置的通信接口（UART/SPI/Bluetooth）接收 GBL 升级文件数据包。
3

验证并写入映像

Bootloader 解析 GBL 文件，可选地验证签名和解密，然后将新固件写入主闪存，覆盖现有应用程序。
4

引导至应用程序

升级完成后，Bootloader 验证新应用程序（若启用 Secure Boot），然后跳转执行。

​
Application Bootloader 操作流程

1

应用程序下载升级映像

正在运行的应用程序通过任意方式（OTA、UART、Ethernet 等）将 GBL 文件下载到下载空间（内部或外部存储）。
2

应用程序请求升级

应用程序调用 bootloader_rebootAndInstall() 通知 Bootloader 执行升级。
3

Bootloader 验证映像

Bootloader 从存储槽中读取 GBL 文件，验证完整性和真实性（若启用签名验证）。
4

写入并引导

Bootloader 将 GBL 内容写入目标闪存区域，完成后引导至新的应用程序。

​
在 Simplicity Studio 5 中创建 Bootloader 项目

1

创建新项目

在 Simplicity Studio 5 的 Launcher 视图中，选择目标设备，点击 Create New Project，在项目向导中选择 Bootloader 类别的示例项目。
2

选择示例配置

根据使用场景选择预置的示例 Bootloader，例如：
  • UART XMODEM Bootloader（Standalone，UART 接口）
  • SPI Flash Storage Bootloader（Application，外部 SPI 闪存）
  • Internal Storage Bootloader（Application，内部闪存）
  • Bluetooth AppLoader OTA DFU Bootloader（OTA 升级）
3

通过 Project Configurator 安装和配置组件

打开项目的 .slcp 文件，在 Software Components 视图中安装所需组件并配置参数。
4

构建和烧录

构建项目，生成 Bootloader 映像，使用 Simplicity Commander 烧录到设备。

​
插件/组件系统

Gecko Bootloader 通过组件系统实现高度可配置性，组件分为以下几大类：
提供 Bootloader 与主机设备通信的接口：
组件协议适用场景
UART: XMODEMUART + XMODEM 协议EmberZNet NCP
UART: BGAPIUART + BGAPI 协议Bluetooth NCP
SPI: EZSPSPI + EZSP 协议Zigbee NCP
Bluetooth: AppLoaderBLE OTABluetooth SoC

​
存储配置示例

SPI Flash Storage 配置：存储区基地址在 Common Storage 组件配置，存储槽在 Bootloader Storage Slot Setup 中设置，SPI GPIO 引脚在 Bootloader SPI Controller Driver 中配置。 Internal Storage 配置参考：
设备型号Storage OffsetStorage Size
512 kB 设备（flash base 0x00）0x44000196608 bytes
1 MB 设备（flash base 0x00）0x84000458752 bytes
2 MB 设备（flash base 0x00）0x100001011712 bytes
默认 Bootloader 提供的存储槽配置必须根据具体用例修改，以匹配 Application 的存储布局。在不同设备上运行 Internal Storage Bootloader 之前，应先修改存储布局。

​
Application Interface（btl_interface.h）

Bootloader 通过内部函数表向应用程序暴露 API，通过 api/btl_interface.h 头文件访问。
如果未使用 Silicon Labs 的协议栈，可直接使用 btl_interface.h 中的 API；如果使用了 Silicon Labs 协议栈，建议使用各协议栈推荐的 Bootloader 接口 API。
接口实现文件：
  • api/btl_interface.c：通用接口实现
  • api/btl_interface_storage.c：存储功能接口实现

​
核心 API 模块

适用于所有版本的 Bootloader，与已安装的组件无关，包括初始化、重启等基础功能：
// 初始化 Bootloader 接口
int32_t bootloader_init(void);

// 反初始化 Bootloader 接口
int32_t bootloader_deinit(void);

// 获取 Bootloader 信息
void bootloader_getInfo(BootloaderInformation_t *info);

// 重启并安装已存储的升级映像
void bootloader_rebootAndInstall(void);

// 验证应用程序映像的签名
int32_t bootloader_verifyApplication(uint32_t startAddress);
仅在支持存储的 Application Bootloader 上可用，用于读写升级映像到存储槽：
// 获取存储槽数量
int32_t bootloader_getNumberOfStorageSlots(void);

// 获取存储槽信息（地址、大小）
int32_t bootloader_getStorageSlotInfo(uint32_t slotId,
                                      BootloaderStorageSlot_t *slot);

// 从存储槽中读取数据
int32_t bootloader_readStorage(uint32_t slotId,
                                uint32_t offset,
                                uint8_t  *buffer,
                                size_t   length);

// 向存储槽写入数据
int32_t bootloader_writeStorage(uint32_t    slotId,
                                 uint32_t    offset,
                                 const uint8_t *buffer,
                                 size_t      length);

// 擦除存储槽
int32_t bootloader_eraseStorageSlot(uint32_t slotId);

// 验证存储槽中 GBL 文件的完整性和真实性
int32_t bootloader_verifyImage(uint32_t slotId, BootloaderParserCallback_t callback);

// 获取存储槽中 GBL 文件的 Application 信息
int32_t bootloader_getImageInfo(uint32_t slotId,
                                ApplicationData_t *appInfo,
                                uint32_t          *bootloaderVersion);
用于解析 GBL 文件内容，在不执行升级的情况下提取元数据：
// 初始化 GBL 解析器上下文
int32_t bootloader_initParser(BootloaderParserContext_t *context,
                               size_t contextSize);

// 解析 GBL 数据块
int32_t bootloader_parseBuffer(BootloaderParserContext_t *context,
                                BootloaderParserCallbacks_t *callbacks,
                                uint8_t buf[],
                                size_t size);

​
典型使用示例

以下示例展示了如何在应用程序中使用 btl_interface.h 完成存储升级映像并触发升级的完整流程： 
#include "btl_interface.h"
#include "btl_interface_storage.h"

void performFirmwareUpdate(uint8_t *gblData, size_t gblSize)
{
    int32_t ret;
    uint32_t slotId = 0;

    // 初始化 Bootloader 接口
    ret = bootloader_init();
    if (ret != BOOTLOADER_OK) {
        // 初始化失败，处理错误
        return;
    }

    // 擦除目标存储槽
    ret = bootloader_eraseStorageSlot(slotId);
    if (ret != BOOTLOADER_OK) {
        bootloader_deinit();
        return;
    }

    // 将 GBL 数据写入存储槽
    ret = bootloader_writeStorage(slotId, 0, gblData, gblSize);
    if (ret != BOOTLOADER_OK) {
        bootloader_deinit();
        return;
    }

    // 验证存储槽中的 GBL 映像
    ret = bootloader_verifyImage(slotId, NULL);
    if (ret != BOOTLOADER_OK) {
        // 映像验证失败
        bootloader_deinit();
        return;
    }

    // 反初始化并重启以安装升级
    bootloader_deinit();
    bootloader_rebootAndInstall();
}

​
错误码分组

大多数 Gecko Bootloader API 返回错误码，主要分组如下：
错误码说明
0x0OK（成功）
0x01xx初始化错误
0x02xx映像验证错误
0x04xx存储错误
0x05xx引导加载错误（Bootload error）
0x06xx安全错误
0x07xx通信错误
0x09xxXMODEM 解析器错误
0x10xxGBL 文件解析器错误
0x11xxSPI 从设备驱动错误
0x12xxUART 驱动错误
0x13xx压缩错误
完整错误码列表可在 SDK 的 platform/bootloader/api/btl_errorcode.h 中找到。

​
Application Properties 结构

Application 映像应包含 ApplicationProperties_t 结构，声明版本、功能和其他元数据。安装 bootloader_interface 组件后，该结构会自动添加到项目中。
1

安装 bootloader_interface 组件

在 Simplicity Studio 5 Project Configurator 中，搜索并安装 bootloader_interface 组件，它会自动安装 bootloader_app_properties 子组件。
2

配置 App Properties

在 Platform > Bootloader > App Properties 组件中点击 Configure，设置 Application 版本号。版本号也可通过宏 APP_PROPERTIES_VERSION 在 Additional Macros 中定义。
3

确认生成的文件

组件添加了 app_properties.c 源文件和 app_properties_config.h 配置文件，Application 类型由无线栈自动填充，可在 autogen/sl_application_type.h 中查看。
如果 Application 中缺少 ApplicationProperties_t 结构，则无法对 Application 映像进行签名，Simplicity Commander 会报错。

​
使用 Simplicity Commander 操作 GBL 文件

# 从应用程序创建未签名 GBL 文件
commander gbl create myapp.gbl --app myapp.s37

# 创建 Bootloader 升级 GBL 文件
commander gbl create mybootloader.gbl --bootloader mybootloader.s37

# 创建 SE 升级 GBL 文件
commander gbl create mySecureElement.gbl --seupgrade mySecureElement.seu

# 生成签名密钥对
commander util genkey --type ecc-p256 \
  --privkey signing-key \
  --pubkey signing-key.pub \
  --tokenfile signing-key-tokens.txt

# 为 Secure Boot 对应用程序映像签名
commander convert myapp.s37 \
  --secureboot \
  --keyfile signing-key \
  --outfile myapp-signed.s37

# 创建签名并加密的 GBL 升级文件
commander gbl create myapp.gbl \
  --app myapp.s37 \
  --sign signing-key \
  --encrypt encryption-key
Series 1 设备不同 Bootloader 配置的典型 Main Bootloader 大小：XMODEM UART 默认配置约 12.8 kB，启用 Secure Boot + 签名/加密升级后仍约 12.8 kB，添加 LZMA 压缩后约 17.9 kB。超过 14 kB 的 Bootloader 无法放入 EFR32xG13 的 Bootloader 闪存区。

Build docs developers (and LLMs) love

Get started for freeTalk to us