一个需要由 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 构建一个 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、编译、签名、烧录或连接硬件,也没有修改网络。实际构建与板上启动仍需在匹配环境中验证,不能将文中的预期观察项登记为已通过结果。
来源与许可
- MCUboot with sysbuild,Zephyr 4.4.0 文档入口。
- 官方 v4.4.0 README 完整正文;配置、源码和 sample.yaml。
- 同版本模块清单;SDK_VERSION。
应用源码原始版权为 © 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.












暂无评论内容