Zephyr 主要子系统与公共库

1. Logging

路径：

subsys/logging/
include/zephyr/logging/

模块注册：

LOG_MODULE_REGISTER(name, CONFIG_NAME_LOG_LEVEL);
LOG_INF("value=%d", value);

架构：

call site
→ compile-time level/filter
→ log message/package
→ immediate 或 deferred processing
→ runtime filter
→ backend (UART/RTT/USB/FS/network...)

Immediate

调用线程直接格式化并输出：

• 实现简单；
• crash 前更容易看到日志；
• ISR 和实时路径延迟大；
• backend 可能阻塞。

Deferred

消息先进入 buffer，由 logging thread 处理：

• 减少调用点延迟；
• 需要 buffer 和线程 stack；
• buffer 满时可能 drop/block；
• reset 前未处理日志可能丢失。

生产配置需要在可观测性、RAM 和 worst-case latency 间权衡。

2. Shell

路径：

subsys/shell/
include/zephyr/shell/

command 通过 linker section 静态注册：

SHELL_CMD_REGISTER(name, subcmd, help, handler);

组成：

• shell core/parser；
• command tree；
• backend（UART、RTT、Telnet、USB CDC 等）；
• history、wildcard、help、log integration；
• subsystem commands。

handler 运行在 shell thread，长操作仍会阻塞 shell。危险生产命令应进行权限、状态和物理访问控制。

3. Settings

路径：

subsys/settings/
include/zephyr/settings/

逻辑：

settings subsystem
├─ handler tree: name/get/set/commit/export
└─ storage backend: NVS/FCB/file/custom

启动：

settings_subsys_init();
settings_register(&handler);
settings_load();

set 解析单项，commit 在整批 load 后应用依赖关系。升级时要考虑 schema version、默认值和向后兼容。

4. Storage 与 Flash map

subsys/storage/flash_map 把 DTS fixed-partitions 暴露为：

flash_area_open
flash_area_read
flash_area_write
flash_area_erase
flash_area_get_sectors

subsys/storage/stream 提供顺序写 abstraction，DFU/flash image writer 可在内部处理 block alignment 和 buffering。

常见持久化技术：

• NVS：key-value，扇区轮转；
• FCB：append-only entry；
• littlefs：掉电安全文件系统；
• settings over NVS/FCB/file。

5. 文件系统

路径：

subsys/fs/
include/zephyr/fs/

VFS API：

• mount/unmount；
• open/read/write/seek/close；
• stat；
• opendir/readdir；
• truncate/unlink/rename。

后端包括 littlefs、FAT、ext2、NVS/FCB 等不同类别。文件系统工作线程/锁、block device、cache 和掉电策略取决于具体后端。

6. DFU

路径：

subsys/dfu/
include/zephyr/dfu/

主要组件：

• flash image buffered writer；
• image validation utilities；
• MCUboot application API；
• target/stream abstraction。

应用使用 MCUboot 时：

接收 image
→ flash_img_buffered_write 到 secondary
→ 校验 header/hash
→ boot_request_upgrade(TEST/PERM)
→ reboot
→ 新应用 boot_write_img_confirmed()

DFU 接收成功不等于镜像可信，最终信任由 bootloader 签名验证建立。

7. MCUmgr

路径：

subsys/mgmt/mcumgr/
include/zephyr/mgmt/mcumgr/

层次：

transport (UART/BLE/UDP/shell...)
→ SMP framing
→ CBOR decode
→ management group
→ command handler

常用 group：

• OS；
• image；
• filesystem；
• shell；
• settings；
• statistics。

server 与 client API 均存在。生产环境必须设计认证、授权和 transport 暴露范围；协议可达不代表命令应对所有调用者开放。

8. Network stack

路径：

subsys/net/
include/zephyr/net/

层次：

application
├─ BSD sockets / native net_context
├─ HTTP/MQTT/CoAP/DNS/DHCP/SNTP/LwM2M/TLS
├─ TCP/UDP/IPv4/IPv6/6LoWPAN
├─ net_if / connection manager
├─ L2: Ethernet/Wi-Fi/802.15.4/PPP/CANbus/virtual
└─ network device driver

核心对象：

• net_if：接口配置、地址、状态；
• net_pkt：packet metadata；
• net_buf：分片数据；
• net_context/socket；
• L2 API；
• network management event。

packet/buffer 来自固定 pool，配置不足表现为运行时分配失败而非普通 heap 增长。应按最大并发连接、窗口、MTU 和协议层开销估算。

9. Socket 与 TLS

Zephyr 提供 POSIX 风格 sockets，可由 native stack 或 offload driver 实现。TLS credentials 子系统按 tag 管理：

• CA；
• client certificate；
• private key；
• PSK。

TLS heap/stack、entropy、证书时间校验和硬件 crypto 会显著影响资源与启动依赖。

10. USB

当前工作区没有 subsys/usb 和 drivers/usb* 实现目录，只残留部分 include/zephyr/drivers/usb/、usb_c/ 头文件以及 DTS bindings。这是源码裁剪后的不完整接口面：

• 不能仅通过打开上游 USB Kconfig 选项获得可用 stack；
• 引用上游 USB sample 前应先恢复对应源码和依赖；
• MCUboot 中存在 USB DFU 配置也不代表当前 Zephyr 主树已具备所需 USB device stack。

11. Power management

路径：

subsys/pm/
include/zephyr/pm/

系统 idle 时：

scheduler 无 runnable work
→ PM policy 选择 state
→ suspend devices
→ SoC/arch 进入低功耗
→ wake event
→ resume devices
→ 恢复调度

policy 可根据下一个 timeout、latency、residency 和 application constraint 决策。busy wait、永久 clock request、未配对 runtime PM 都会阻止低功耗。

12. Random 与 Entropy

subsys/random 提供：

• non-cryptographic random；
• cryptographically secure random；
• entropy driver 接入。

安全用途必须调用 CSPRNG API，并确认：

• hardware entropy device ready；
• seed 不可预测；
• 启动早期不会静默退化；
• health test 和错误传播合理。

13. Debug、Coredump 与 Tracing

路径：

subsys/debug/
subsys/tracing/
subsys/timing/

能力包括：

• coredump；
• gdbstub；
• symbol table；
• thread analyzer；
• stack usage；
• CTF/SystemView tracing；
• execution timing；
• runtime stats。

这些功能改变 timing 和内存布局，性能结论应区分 instrumentation build 与 release build。

14. Zbus

subsys/zbus 提供 channel/observer 消息总线：

• listener；
• subscriber；
• message subscriber；
• runtime observer registration；
• priority boost。

适合模块解耦和状态广播。channel message 是共享数据，需理解 publish copy、observer 执行上下文和阻塞行为。

15. RTIO

subsys/rtio 提供异步 I/O submission/completion queue：

• SQE/CQE；
• executor；
• chained operations；
• sensor/I2C/SPI 等适配。

目标是减少逐次同步调用开销，支持批量和异步 pipeline。buffer 生命周期和 completion 消费是正确性的关键。

16. IPC

subsys/ipc 包括：

• IPC service；
• RPMsg service；
• backend abstraction；
• endpoint bind/send/receive。

多核系统还依赖 shared memory、mailbox/IPI、cache coherence 和 remote firmware 生命周期。

17. Modem、Bluetooth 与协议组件

当前树存在 modem 相关实现，但没有 subsys/bluetooth 源码；include/zephyr/bluetooth/ 等残留头文件不能视为可链接实现。若从外部模块恢复复杂无线协议，它通常横跨：

• controller/driver；
• host stack；
• network/L2；
• settings 持久化；
• workqueue/thread；
• security/crypto；
• management events。

排查不能只看单个 driver，需从 transport buffer、协议 thread priority、workqueue 和 memory pool 联合分析。

18. 公共库

lib/ 和 include/zephyr/sys/ 提供：

• singly/doubly linked list；
• ring buffer；
• byte order；
• CRC/hash/checksum；
• JSON；
• CBOR；
• base64；
• heap；
• bitarray/bitmap；
• math/time utilities；
• POSIX compatibility；
• minimal/newlib/picolibc integration。

公共库应优先于项目内重复实现，但需检查 Kconfig、线程安全、ISR safe 和内存分配行为。

19. 子系统集成原则

1. 明确 thread/workqueue/context；
2. 明确 buffer ownership；
3. 明确 Kconfig 和 DTS 双重依赖；
4. 对持久化数据做 schema 和掉电设计；
5. 对外部管理接口做授权；
6. 对 memory pool 做容量推导；
7. 对 logging/debug 的实时性影响做 release 验证；
8. 避免多个子系统争用同一 UART、flash partition 或 workqueue。