一句话结论：Zephyr 的系统设计，本质是用「Devicetree 描述硬件 + Kconfig 裁剪功能 + 设备模型统一初始化」把「几百块板卡各自手写板级代码」变成「一份应用配置 + 一份 overlay」。 它比 FreeRTOS 多了设备树、统一的设备初始化等级与可复用的网络/蓝牙/存储子系统，比 Linux 少了MMU 与进程抽象——代价是必须接受 Kconfig 与 DT 这两层编译期抽象的学习曲线。 线上故障最集中的四处：overlay 写了但设备没使能（status 仍为 disabled）、设备就绪检查被跳过、ISR 里调用了阻塞 API、栈与堆被低估后随机踩踏。管住这四处，系统稳定性解决八成。

这份文档解决什么

本文是 Zephyr 系统级开发总文档：从 west 工作区与工具链、内核线程与同步原语、设备模型与初始化等级、Devicetree 与 Kconfig、构建系统，到工作队列、日志诊断、存储子系统、网络蓝牙、性能低功耗、可靠性与 MCUboot OTA、测试与发布，构成一条完整链路。 具体的驱动编写（外设驱动、存储器件驱动、文件系统挂载）由配套的《Zephyr 驱动开发指南》承接；本文只讲「在这一层如何把系统组装起来、如何把驱动挂进系统」。器件级电气与时序细节仍以各器件的设计指南为准。

使用约定

• API、目录与配置项以 Zephyr 3.7 LTS / 4.x 为主线，兼顾 3.5 及更早版本；差异明显处单独标注。目标平台以 Cortex-M3/M4/M33/M55、RISC-V 为主。
• 代码示例只保留系统层逻辑；具体寄存器操作统一写成 /* SoC 层提供 */ 注释。
• 标 红线 为强制约束，标 警惕 为高频踩坑点，标 建议 为经验推荐值。
• 文中出现的默认数值（栈大小、优先级、缓冲区大小、宏名）以官方仓库与 Kconfig 为参考；不同版本宏名与默认值可能变化，落地前以工程内 build/zephyr/.config 与 zephyr.dts 为准。
• 芯片参数、时钟、外设行为一律以官方 datasheet 与 Zephyr 官方文档 / 源码为准。

1 · 文档概述与 Zephyr 架构

这一章解决三件事：这份文档覆盖到哪一层、Zephyr 由哪些层构成、它和 Linux / FreeRTOS / RT-Thread 的边界在哪。读完再决定后面该精读哪几章。

1.1 编写目的、适用范围与读者

本指南面向基于 Zephyr 做系统级开发的工程团队：把一颗裸的 MCU 变成可量产、可升级、可运维的终端设备。它要回答的不是「某个寄存器怎么写」，而是「一堆驱动、子系统与应用如何按正确顺序长成一个系统」。

1.2 版本基线、支持平台与分支策略

Zephyr 有两条实际在用的版本线：3.7 LTS（长期支持，稳定性优先，适合量产）与 4.x（新特性跟进更快）。本指南以 3.7 LTS 为主、4.x 兼容，差异较大处显式标注。

1.3 术语与缩写

1.4 五层架构总览

Zephyr 采用分层架构 + 编译期声明双视角：分层决定「谁能调用谁」，声明决定「编译时包含什么、硬件怎么连」。两者叠加的效果是——应用只写业务与配置，硬件细节全部由设备树供给。

• ⑤ 应用层：你的业务代码与官方 samples。唯一「自己写」的一层，也是唯一不随芯片变化的层。
• ④ 子系统层：存储、网络、蓝牙、日志、追踪等可裁剪的中间件。裁剪由 Kconfig 决定，未使能的子系统链接时完全不进镜像。
• ③ 设备模型层：Zephyr 的枢纽。struct device 承载状态，API 表承载操作，初始化等级决定谁先起来。它让「换一颗芯片不改应用」成为可能。
• ② 内核层：线程、调度、同步原语、内存分配器、工作队列、定时器。多核下由 SMP 支撑。
• ① 硬件抽象层：arch（内核移植）、SoC 层（时钟与外设驱动）、board 层（板级 DTS 与分区）、以及贯穿全局的 Kconfig 裁剪。

1.5 与 Linux / FreeRTOS / RT-Thread / AliOS 的差异

选型时最常问的问题是「Zephyr 比 Linux 多了什么、比 FreeRTOS 多了什么」。下表按能力维度对照，深色列为 Zephyr。

逐条说明差异的实际含义：

1.6 阅读路线图

2 · 开发环境与 west 工作区

这一章解决：怎么把一套能复现的 Zephyr 开发环境搭起来，以及 west 工作区、Zephyr SDK、你的应用三者的关系。环境没搭对，后面所有章节的排查都会失真。

2.1 宿主机依赖与 Zephyr SDK

Zephyr 对宿主机有明确要求。SDK 与工具链版本必须与你的 Zephyr 基线匹配，这是最常见的「明明代码没错却编译不过」的根因。

2.2 west 工作区初始化与模块管理

west 解决的是「Zephyr 由几十个仓库组成」的问题：它按 manifest 把所有 project 拉到同一层目录，并保证各仓库处于声明的 revision 上。

初始化步骤

1. 装依赖：先装 Python、CMake、Git，再 pip install west，最后装匹配的 Zephyr SDK。
2. 初始化工作区：west init ~/zephyrproject（已有仓库可 west init -l <已有目录> 就地接管）。
3. 更新全部仓库：west update，把 manifest 声明的所有 project 拉到指定 revision。
4. 装 Python 包：pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt。
5. 设置环境变量：把 ZEPHYR_BASE 指向 ~/zephyrproject/zephyr，把 ZEPHYR_TOOLCHAIN_VARIANT 设为 zephyr（用 SDK 时）。
6. 验证：构建一次官方 sample，确认工具链与串口日志都通。

# 1) 装 west 与 Python 依赖
pip install west
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

# 2) 初始化工作区（首次）
west init ~/zephyrproject
cd ~/zephyrproject
west update

# 3) 指定 SDK 并验证
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0

# 4) 跑通第一个应用（以官方 sample 验证环境）
west build -b qemu_cortex_m3 zephyr/samples/hello_world
west build -t run          # native_sim / qemu 可直接跑，不需要真板

2.3 三种应用形态与选型

Zephyr 官方定义了三种应用与源码的相对位置关系。选错了会导致 ZEPHYR_BASE 找不到、或应用被 Zephyr 更新冲掉。

三个要点：

• T2 是生产项目的默认选择：你的应用就是一个独立的 Git 仓库，通过 west.yml 把 Zephyr、MCUboot、厂商 HAL 的 commit 钉死。构建可复现、CI 好做、升级节奏自控（详见 19.1）。
• T1 适合验证：改官方 sample 最省事，但不要用于量产——它会随 Zephyr 仓库变动。
• T3 适合跨团队：应用与 Zephyr 彻底分离，但要自己保证 ZEPHYR_BASE 与 SDK 环境变量在所有机器上一致。

2.4 工程目录结构详解

一个结构良好的应用目录，能让新同事在半天内看懂「配置在哪、代码在哪、板级差异在哪」。推荐如下布局：

my-product/
├── west.yml                 # 清单：钉住 zephyr / mcu_boot / hal_* 的 commit
├── CMakeLists.txt            # find_package(Zephyr) + target_sources
├── prj.conf                  # 基础 Kconfig：所有板子共用的配置
├── VERSION                   # 版本号（签名与上报用）
├── app.overlay               # 基础 overlay：所有板子共用的硬件变更
├── boards/
│   ├── <board1>.conf         # 板级配置：只放该板特有项
│   ├── <board1>.overlay      # 板级 overlay：引脚 / 外设差异
│   └── custom_board/         # 自定义板：dts / defconfig / yaml / Kconfig.board
├── src/
│   ├── main.c                # 应用入口
│   ├── ble/                  # 按子系统分目录，各自独立编译
│   │   └── CMakeLists.txt
│   ├── sensors/
│   │   └── CMakeLists.txt
│   └── storage/              # 存储业务逻辑
│       └── CMakeLists.txt
├── include/                  # 对外头文件
├── drivers/                  # out-of-tree 驱动（不进 Zephyr 源码树）
│   └── my_flash/
│       ├── CMakeLists.txt
│       ├── my_flash.c
│       └── dts/bindings/vendor,my-flash.yaml
├── tests/                    # ztest 用例与 testcase.yaml
│   ├── CMakeLists.txt
│   └── prj.conf
├── scripts/                  # 构建、烧录、签名辅助脚本
└── child_image/              # 子镜像配置（如 MCUboot 的 Kconfig 片段）
    └── mcuboot.conf

2.5 west 常用命令速查

2.6 构建产物与烧录

Zephyr 不支持 in-tree 构建，产物全部落在独立的 build/ 目录。知道每个产物是什么、留哪个做现场分析，才能在出问题时不至于抓瞎。

2.7 native_sim 主机仿真

Zephyr 有一个常被忽视的能力：把整个系统编译成宿主机原生程序，在 PC 上跑起来。板级代码与真实外设不可用，但内核、驱动逻辑、协议栈、存储子系统都能真实执行。

# 编译为宿主机程序并直接运行（无需任何硬件）
west build -b native_sim ~/zephyrproject/my-product
west build -t run

# 常用配套手段
#   - 单元测试：把被测逻辑写成 ztest，用 native_sim 跑
#   - 逻辑层：协议解析、状态机、算法、数据结构都能在此验证
#   - 配合 CONFIG_ARCH_POSIX，可用 ptrace/gdb 调宿主程序

3 · 内核线程与调度

这一章解决：线程是怎么创建与切换的、优先级怎么设才算合理、栈与内核内存从哪来、多核下要注意什么。线程模型没想清楚，后面的并发缺陷与环境无关 bug 会集中爆发。

3.1 线程模型与生命周期

Zephyr 内核是可抢占的实时内核：默认按优先级抢占，支持协作式调度（优先级设为负数）与时间片（可选）。一个应用在编译期最多可用的线程数由配置决定，运行时由内核统一管理。

创建线程的基本形态如下，注意启动延迟与栈大小两个参数：

#include <zephyr/kernel.h>

/* 线程入口：返回即终止 */
static void sensor_thread(void *a, void *b, void *c)
{
    while (1) {
        /* 周期性工作 */
        sample_and_process();
        k_msleep(1000);       /* 让出 CPU，进入阻塞态 */
    }
}

/* 静态方式：栈与控制块由应用提供，链接期确定，无运行时分配 */
K_THREAD_STACK_DEFINE(sensor_stack, 2048);
static struct k_thread sensor_thr;
static struct k_sem sensor_sem;

K_THREAD_DEFINE(sensor_tid, 2048, sensor_thread, NULL, NULL, NULL,
                5, 0, 500);    /* 优先级 5、启动延迟 0、立即启动 */

/* 动态方式：栈由内核内存池分配，适合数量与栈大小运行期才确定的场景 */
int sensor_start(void)
{
    k_tid_t tid = k_thread_create(&sensor_thr, sensor_stack,
                                  K_THREAD_STACK_SIZEOF(sensor_stack),
                                  sensor_thread, NULL, NULL, NULL,
                                  5, 0, K_NO_WAIT);
    if (tid == NULL) {
        return -EAGAIN;   /* 内存不足 */
    }
    return 0;
}

3.2 优先级与抢占模型

Zephyr 的优先级数值越小越优先，范围通常是 -1 到 NUM_PRIORITIES-1。其中负值表示协作式（不可被抢占，只在显式让出时切换），非负表示抢占式。

三条排优先级的实用准则

1. 线程优先级数量控制在 5~7 档以内。档位越多，每档至少一个线程，栈与内存开销线性增长；档位过密则优先级反转的复杂度上升。
2. 0 档留给「普通后台」，所有不需要实时性的业务线程都放这一档；实时线程只给真正有时序要求的那几条。常见错误是给每个外设都开一个高优先级线程，导致高优先级线程长期霸占 CPU。
3. 用完高优先级必须主动阻塞：实时线程做完事就 k_msleep 或等信号量，不要空转等待。红线 空转的高优先级线程会让所有低优先级线程饿死，是「系统偶尔卡住」的头号原因。

3.3 调度器实现机制

Zephyr 的调度器有两个实现可换，行为差异明显：

调度器锁存点（z_reschedule）发生在中断退出、阻塞 API 返回、显式让出三个时机。理解这一点能解释一个常见现象：为什么在中断里改优先级后，被提升的线程不是立刻运行，要等中断返回——因为调度判定在中断退出时统一做。

/* 典型正确用法：中断只做「标记 + 唤醒」，重活放工作队列 */
static void sensor_isr(const struct device *dev)
{
    struct sensor_ctx *ctx = dev->data;
    /* ISR 内允许：读设备状态、置标志、k_sem_give / k_work_enqueue */
    k_sem_give(&ctx->data_ready);
    /* ISR 内禁止：k_mutex_lock、k_msleep、打印、动态内存分配 */
}

3.4 线程栈与内核内存

Zephyr 的栈有两种来源，这与 FreeRTOS 常见做法不同，也是最易踩坑的地方。

3.5 SMP 与多核支持

Zephyr 支持对称多核（SMP），但多核支持需要 SoC 与板级配合：SoC 层需实现 CONFIG_SMP 下的 CPU 启动与中断路由，板级 DTS 需描述各核（通常是 cpus 节点）。

4 · 同步原语与线程通信

这一章解决：用什么原语保护共享资源、怎么在线程间传数据、死锁与优先级反转怎么防。并发缺陷是 Zephyr 系统里最难复现也最难查的一类问题，核心纪律是「提前设计」而不是「事后调试」。

4.1 互斥量与信号量

Zephyr 的互斥类原语有四种，最常用的两个是 k_mutex 与 k_sem，选错会导致隐性 bug。

另外三条容易忽略的细节：

• 一个锁只保护一个资源。不要用一把全局大锁保护所有共享数据——正确做法是「每个资源一把锁」，减少锁竞争与持锁时间。
• 解锁必须用 k_mutex_unlock 且路径唯一。用 goto 汇到统一出口解锁，是 C 语言里最稳的写法。
• k_sem 没有优先级继承。所以它不能用来保护共享资源，只能用来「通知」。用信号量做互斥是常见且隐蔽的错误。

/* 推荐写法：单资源单锁 + 统一出口解锁 */
struct dev_ctx {
    struct k_mutex lock;          /* 只保护本驱动的状态 */
    struct device_state state;
    bool busy;
};

static int dev_write(struct dev_ctx *c, const void *buf, size_t len)
{
    int rc = 0;

    if (k_mutex_lock(&c->lock, K_FOREVER) != 0) {
        return -EBUSY;
    }
    if (c->busy) {                 /* 业务条件判断也放在锁内 */
        rc = -EBUSY;
        goto out;                  /* 统一出口，避免漏解锁 */
    }
    c->busy = true;
    /* 真正的寄存器操作放在这里，且尽量短 */
    hw_write(buf, len);

out:
    if (rc == 0) {
        c->state = STATE_IDLE;
    }
    c->busy = false;
    k_mutex_unlock(&c->lock);
    return rc;
}

4.2 消息队列与 FIFO

需要在线程间传数据时用消息队列或 FIFO，而不是轮询共享变量 + 标志位。

两条实战要点：

1. 优先用 k_msgq 而非「环形缓冲 + 锁」。手写环形缓冲的锁保护与满/空判断是 bug 高发区；消息队列把这些边界处理内建了。
2. 消息体不要直接传大结构体指针，除非你保证指针指向的对象在接收侧处理完之前不会被释放。传指针的风险是生命周期不受控——这是嵌入式里最难查的一类 use-after-free。

/* 推荐：定长消息按值传递，生命周期完全可控 */
struct sensor_sample {
    uint32_t timestamp;   /* ms */
    int16_t  temp_c10;    /* 温度 x10，避免浮点 */
    uint16_t humidity_c100;
};

K_MSGQ_DEFINE(sample_q, sizeof(struct sensor_sample), 8, 4);

/* 生产者（可以是线程或工作队列） */
static void on_sample_ready(const struct sensor_sample *s)
{
    /* 非阻塞发送：队列满时返回 -ENOMSG，由调用方决定丢弃还是覆盖 */
    int rc = k_msgq_put(&sample_q, s, K_NO_WAIT);
    if (rc == -ENOMSG) {
        /* 必须处理「满了」：丢弃最旧、覆盖新值、或降采样 */
    }
}

/* 消费者线程 */
static void consumer_thread(void *a, void *b, void *c)
{
    struct sensor_sample s;
    while (1) {
        if (k_msgq_get(&sample_q, &s, K_FOREVER) == 0) {
            process(&s);
        }
    }
}

4.3 事件位与广播

当一个状态变化需要通知多个订阅方时，用事件位（k_event）比广播指针更安全——它只传递「发生了什么」，不传递「数据在哪」。

/* 事件位：只传状态，不传指针，从根上避免悬垂指针 */
#define EVT_SENSOR_READY   BIT(0)
#define EVT_SENSOR_ERROR   BIT(1)
#define EVT_LOW_BATTERY    BIT(2)

/* 发送方：设置位并广播 */
k_event_set(&app_events, EVT_SENSOR_READY);

/* 接收方：等待任意位或指定位 */
uint32_t events = EVT_SENSOR_READY | EVT_SENSOR_ERROR;
k_event_wait(&app_events, events, false, K_FOREVER);

/* 非阻塞轮询版本：适合在主循环里检查 */
if (k_event_test(&app_events, EVT_LOW_BATTERY)) {
    handle_low_battery();
}

k_event 的价值在于把「状态」与「数据」分离：接收者被唤醒后，自己决定去哪里读数据（例如从一个受锁保护的上下文中读）。 这比传递指针更安全，也更容易扩展（新增订阅者不改发送方）。

4.4 死锁与优先级反转

并发缺陷有两类典型形态：死锁是「双方互等」的直接卡死，优先级反转是「高优先级被低优先级间接阻塞」的隐性饥饿。两者都必须在设计阶段消除，靠调试是碰运气。

死锁的预防清单

• 全局固定加锁顺序：需要同时持多把锁时，按锁地址（或编号）升序加锁，绝不反序。
• 临界区内不做阻塞操作：锁内禁止 k_msleep、k_msgq_get(K_FOREVER)、printf、动态分配。
• 用带超时的获取：关键路径用 k_mutex_lock(&lock, K_MSEC(50))，超时后走降级路径，而不是无限等待。
• 用 K_NO_WAIT 试探：不可重入的场合先试探，失败就返回 -EBUSY 交给上层重试，避免原地死等。
• 锁的数量控制在最小：能用单锁解决就不要两锁；需要两锁时优先考虑「合并成一个锁 + 临界区内处理」。

优先级反转的预防清单

• 保护共享数据一律用 k_mutex（默认开启优先级继承），不要用 k_sem 做互斥。
• 缩短持有时间：持锁期间只做「必须原子完成」的最短操作，耗时计算放到锁外。
• 不要在锁内做 I/O：Flash 读写、SPI 传输、串口发送都可能长时间占用总线，放在锁内会显著拉长临界区。
• 提高共享资源的持有者优先级：如果某资源被一个固定线程独占，可把该线程优先级提到使用者之上。

4.5 原语选型决策表