Zephyr Sysbuild:一起构建 MCUboot 与应用固件

一个需要由 MCUboot 引导的应用,不能只构建自己的固件镜像。Zephyr 的 Sysbuild 可以把应用与引导程序纳入同一次系统级构建,让相关镜像使用相互配合的配置。官方 with_mcuboot 示例展示了这件事,同时演示如何只对额外的 MCUboot 镜像加入专用 Kconfig 片段。

本文完整整理 Zephyr 4.4.0 的 MCUboot with sysbuild 示例,并与官方仓库 v4.4.0 标签下的 README、应用源码、构建配置和测试描述逐项核对。原文由 Zephyr Project 维护,没有单独个人署名。检索日期为 2026 年 10 月 5 日;正文对照同版本官方仓库的完整 README 原文核验。

Sysbuild 配置与启动流程示意:sysbuild.conf 选择 MCUboot 及覆盖模式,独立的 MCUboot 和应用镜像分别构建,然后由 MCUboot 引导应用
编辑绘制的配置与启动示意图。两个镜像分别构建,不表示它们必然合成某种固定格式的单一文件。

这个示例解决什么问题

示例的目标很直接:通过 Sysbuild 构建一个 Zephyr 应用,并自动把 MCUboot 加入为引导程序。它同时演示镜像专用的配置覆盖方式——应用可以保留自己的配置,而 MCUboot 通过单独的 Kconfig 片段改变日志级别和降级防护行为。

这是一份多镜像构建与基本启动示例,不是完整的远程升级服务,也没有给出生产用密钥管理、设备生命周期或故障恢复方案。要做板上验证,需要已经准备好的 Zephyr 工作区、相应工具链、与板型匹配的调试烧录器及控制台连接;本文不会把构建成功等同于设备安全升级能力已经验收。

把版本与板型固定下来

本篇锁定 Zephyr v4.4.0。该标签下的 SDK_VERSION 内容为 1.0.1;west.yml 将 MCUboot 固定在以下提交,并放在 bootloader/mcuboot:

ee39e2d694bd827ffd1bebbce2f571a9154e6ec2

这些版本标记来自本次读取的源文件,不代表已经在本机安装或构建成功。复现时应使用同一版本的工作区和模块依赖,避免混合一个标签的应用、另一个版本的 MCUboot 和旧版配置说明。

官方 README 的构建命令选择 reel_board。同标签 sample.yaml 的允许列表同时包含 reel_board 和 nrf52840dk/nrf52840,以及若干 ESP32、STM32、SAM 等平台。允许列表表示示例的测试配置边界,不能理解为任意 Zephyr 板都能无条件使用。若使用 Nordic 开发板,应写完整目标 nrf52840dk/nrf52840;不要直接把旧日志里较短的板名当作当前构建目标。

先看文件分工,再修改参数

示例目录是 samples/sysbuild/with_mcuboot。本次完整读取的关键文件及职责如下:

文件 职责
sysbuild.conf 系统级构建配置,启用 MCUboot 并选择覆盖模式
sysbuild/mcuboot.conf 只给 MCUboot 镜像追加的配置片段
prj.conf 应用自身配置;该示例只有“Empty file”注释
CMakeLists.txt 声明应用工程、要求使用 Sysbuild、加入 main.c
src/main.c 打印应用镜像地址及板名
sample.yaml 指定 Sysbuild 测试方式、板型范围与控制台匹配规则

把这几类配置都塞到 prj.conf 里,并不能表达同样的系统构建关系。最外层的 Sysbuild 配置与某个镜像自己的 Kconfig 配置,所处层级不同。

sysbuild.conf:启用引导程序并选择工作模式

v4.4.0 示例的实际内容是:

# Sysbuild configuration file.

# Enable MCUboot using overwrite only mode for this sample.
SB_CONFIG_BOOTLOADER_MCUBOOT=y
SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y

SB_CONFIG_BOOTLOADER_MCUBOOT=y 表示在 Sysbuild 构建中加入 MCUboot。SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y 选择此示例的 overwrite-only 覆盖模式。以 SB_CONFIG_ 开头的设置属于 Sysbuild,不要把它改写成应用层的同名 CONFIG_ 设置,也不要只编译应用后假定引导镜像已经一起生成。

“覆盖模式”是这里选择的镜像更新工作方式,不能据此声称具备交换模式的全部回退能力。生产环境是否采用这种模式,要结合分区和升级失败处理设计来决定;本示例只展示该配置如何经 Sysbuild 传递。

mcuboot.conf:调整额外镜像,不再在这里选模式

原文说明这个文件会作为额外片段,与 MCUboot 的默认配置文件一起合并。当前 v4.4.0 文件为:

# Example of sample specific Kconfig changes when building sample with MCUboot
# when using sysbuild. Note that the MCUboot operating mode is not set here as
# sysbuild will automatically set it for both the application and MCUboot images itself
CONFIG_MCUBOOT_LOG_LEVEL_WRN=y
CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y

第一项把 MCUboot 日志级别设为 warning,第二项启用降级防护配置。最上面的注释特别指出:MCUboot 的工作模式不在这里设定,Sysbuild 会为应用和 MCUboot 两个镜像自动配置相应模式。

这里有一处应当明确修正的原文差异:v4.4.0 README 仍把日志、降级防护和 upgrade-only 工作方式一起归到 sysbuild/mcuboot.conf 的说明里;但同标签实际源码已经把模式选择放在 sysbuild.conf。本文保留原文的整体意图,同时以实际配置文件为准。照着旧说明把模式参数全搬到 mcuboot.conf,会忽略 Sysbuild 对两个镜像的统一配置。

应用构建文件与完整 main.c

示例的 CMakeLists.txt 没有复杂逻辑,但它调用了 test_sysbuild(),用来检查是否通过 Sysbuild 构建,确保 MCUboot 自动加入并使用本示例指定的专用配置:

# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(sample_with_mcuboot)

# Verify that this sample is built through sysbuild to ensure MCUboot is
# automatically included and that sample specific MCUboot configurations are
# used when building MCUboot.
test_sysbuild()

target_sources(app PRIVATE src/main.c)

应用侧的 prj.conf 是空配置文件,只包含 # Empty file。这并不表示系统没有配置,而是此例不再通过该文件添加额外应用设置。

应用的完整源码非常短:

/*
 * Copyright (c) 2022 Nordic Semiconductor
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#include <zephyr/kernel.h>
#include <zephyr/linker/linker-defs.h>

int main(void)
{
    printk("Address of sample %p\n", (void *)__rom_region_start);
    printk("Hello sysbuild with mcuboot! %s\n", CONFIG_BOARD);
    return 0;
}

它先打印链接器提供的 __rom_region_start 地址,再打印由 CONFIG_BOARD 提供的板名。%p 对应已经显式转换成 void * 的地址,%s 对应编译期配置的字符串。这里没有网络输入、命令拼接或密钥处理;输出地址的目的,是让使用者能核对应用位于哪个 Flash 区域。

用一次 west build 构建两个镜像

在准备好的 Zephyr 工作区中,按照原 README 对 reel_board 构建,命令展开为:

west build -b reel_board samples/sysbuild/with_mcuboot --sysbuild

--sysbuild 不能省略。它使构建从系统级入口处理 sysbuild.conf,同时包含应用与 MCUboot。若改用允许列表中的 nRF52840 DK,可采用以下板型对应的形式:

west build -b nrf52840dk/nrf52840 samples/sysbuild/with_mcuboot --sysbuild

第二条是根据同标签板型清单补充的例子,不是声称本次在该硬件上跑过。两条命令是二选一,切换板型时应使用独立或干净的构建目录,避免沿用与新板型不匹配的缓存。

构建后应检查系统构建信息是否同时包含应用与 mcuboot 两个域,各自都有对应的构建输出。检查生成的 ELF,以及目标配置启用的 BIN、HEX 等格式和烧录所用镜像,不要只看到一个应用 ELF 就认定引导镜像已经部署。具体路径、输出格式与分区布局依目标板和构建配置确定,本篇没有把它们写成所有硬件都相同的固定路径。

原文的操作步骤止于构建命令与运行输出,并未给出一套通用烧录命令。实际烧录须遵循所选开发板和 runner 的文档,确认调试器、Flash 分区和镜像集合一致。本文因此不凭空补一条面向所有板型的烧录命令。

从控制台判断 MCUboot 与应用是否依次启动

原 README 给出的历史输出如下,完整保留以说明输出结构:

*** Booting Zephyr OS build v3.2.0-rc3-209-gdcf4201d3573  ***
*** Booting Zephyr OS build v3.2.0-rc3-209-gdcf4201d3573  ***
Address of sample 0xc000
Hello sysbuild with mcuboot! nrf52840dk

第一条 Booting Zephyr OS build 来自 MCUboot,后面的启动信息、地址与问候来自 with_mcuboot 应用。这个顺序用于理解“引导程序先运行,再进入应用”。

输出中的 v3.2.0-rc3...、0xc000 和较短的 nrf52840dk 是原文保存的旧示例,不是 Zephyr 4.4.0 的实际运行记录。不要要求新构建逐字输出同一版本或同一地址。应用地址应与所选板型的实际分区及链接结果一致;本次未读取真实设备 Flash,也未验证某一地址正确。

同版 sample.yaml 的控制台验收使用多行匹配,关注两条应用消息:

Address of sample(.*)
Hello sysbuild with mcuboot!(.*)

这说明示例自动化测试核对的是应用确实到达预期输出位置,而不是把历史版号、板名或地址写死。自行验收时,除了看见这些文字,还应结合当前构建版本、镜像部署情况和实际地址来判断,避免把上一次刷入设备的旧固件输出误当成新构建结果。

静态审核发现与运行限制

本次核对了所有示例配置、完整应用源码和构建文件,修正了 README 对模式配置文件的过时归属,并明确标注旧运行输出。源码中的格式字符串是固定字面量,参数类型与转换说明相符;没有发现该范围内的外部输入注入点或明文密钥。但这段打印程序本身不能证明整个引导链、签名校验、降级防护和更新策略都已安全验证。

示例启用 CONFIG_MCUBOOT_DOWNGRADE_PREVENTION 不等于完成生产级防回滚方案;示例的默认签名配置也不能当作生产密钥管理方案。生产系统需要单独管理签名密钥和相应验证配置,并根据所选升级模式检查分区、断电恢复与版本策略。本篇不生成密钥、不替换签名配置,也不宣称做过这类安全测试。

本文只进行安全的静态审核,没有安装 SDK、更新工作区模块、执行 CMake/west、编译、签名、烧录或连接硬件,也没有修改网络。实际构建与板上启动仍需在匹配环境中验证,不能将文中的预期观察项登记为已通过结果。

来源与许可

应用源码原始版权为 © 2022 Nordic Semiconductor,示例源码和 CMake 文件标注 Apache-2.0。完整许可证在文末公开保留,并可查阅 Zephyr v4.4.0 LICENSE。第三方模块应以各自许可为准。中文译写、配置差异说明和原创图属于本次整理;全文译写与配图由未完纪整理制作,不把软件许可证泛化成对所有外部内容的许可。

上游代码版权与完整许可

以下保留对应上游版本的完整声明;第三方例外与附加通知按原文保留。

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "{}"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright {yyyy} {name of copyright owner}

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容