企业官网建设流程全解析

• 操作系统
• 嵌入式
• 嵌入式OS

本篇指南以 doc/README.md 为入口，系统梳理 Tock 安全嵌入式操作系统的完整文档体系，涵盖用户态与内核间的系统调用接口（syscall）、内核内部硬件接口层（HIL）参考、开发环境搭建、代码规范与仓库结构，以及工作小组、代码评审、发布与安全漏洞处理等项目管理机制。读完本文，你将能够依据文档地图快速定位任意开发主题，并了解每类文档背后的实际仓库布局与源码依据。

Tock 文档仓库的整体定位

Tock 的文档以doc/目录为集中存放地，与源码仓库同库维护，这使得文档可以紧贴代码演进、随 PR 同步更新。根据 doc/README.md 的自述，doc/内主要存放Tock 的各类政策与开发实践说明，同时包含两部分接口规格：

• 通用内核文档与教程位于独立的 Tock Book；
• 本目录重点收录 syscall 接口文档（doc/syscalls/）与内核内部接口参考（doc/reference/）。

从仓库结构看，doc/下实际包含 13 个顶层 Markdown 文件，外加reference/（Tock 参考文档 TRD）、rfcs/（请求评论）、syscalls/（系统调用规格）、wg/（工作小组）、images/（CI 硬件图片）等子目录。整体可分为三大类：

1. 接口细节：系统调用接口（syscalls）与内核内部接口（reference/HIL）；
2. 环境搭建与开发：Getting_Started、CodeGoals、Repository、NestedBoards、OutOfTree、Style、ExternalDependencies；
3. 项目管理：Working Groups、CodeReview、Maintenance、SecurityProtocol。

下文逐一展开。

接口细节：用户态与内核的契约

Syscall 接口文档（doc/syscalls）

doc/syscalls/README.md 是用户态与内核之间 ABI 的详细规格，涵盖 ABI 接口、内核自带 syscall，以及基于allow、subscribe、command三原语的驱动级接口。其核心价值在于为每个已分配**永久驱动号（driver number）**的驱动建立登记表，并标注该驱动是否已在 Tock 2.0 中稳定（"✓" 表示稳定）。

核心内核提供的 syscall

内核自身只提供一个核心 syscall：memop（规格文档）。它负责内存相关操作，所有调用均以操作类型作为第一参数，部分调用在第二参数携带参数，签名形如：

memop(op_type: u32, argument: u32) -> [[ VARIES ]]

doc/syscalls/memop.md 完整列出了操作类型定义：

• 操作类型 0（brk）：将程序断点（program break，即进程最大可访问地址）移动到给定绝对地址，返回Result<(), ErrorCode>，内存不足时返回NOMEM；
• 操作类型 1（sbrk）：按指定字节数（i32）上下移动程序断点，返回移动前的程序断点地址（即新分配内存的起始地址），失败返回NOMEM；
• 操作类型 2（Memory start）：获取进程 RAM 分配的起始地址；
• 操作类型 3（Memory end）：获取进程 RAM 分配末尾之后第一个地址；
• 操作类型 4（Flash start）：获取进程 flash 区域起始地址（即 TBF 头所在位置）；
• 操作类型 5（Flash end）：获取进程 flash 区域末尾之后第一个地址；
• 操作类型 6（Grant start）：获取进程 grant 区域的最低地址（grant 末尾即内存末尾，故无对应 grant end syscall）。

在源码层面，memop的处理入口位于 kernel/src/memop.rs，由 kernel/src/kernel.rs 在内核循环中根据系统调用号分派（memop::memop(process, operand, arg0)）；与之相关的进程内存管理实现可见 kernel/src/process.rs（含brk相关注释与可访问内存区约束），以及 kernel/src/process_standard.rs（进程必须通过brkmemop syscall 扩展可访问内存）。

Capsule 提供的驱动号登记表

doc/syscalls/README.md 按功能域列出所有已分配的永久驱动号，是用户态开发者查找驱动接口的第一手资料：

这些驱动的稳定状态记录由 doc/Maintenance.md 定义的"驱动稳定化流程"维护，二者联动（详见下文发布管理一节）。每个有文档的驱动在doc/syscalls/下有独立规格文件（如 00001_console.md、00004_gpio.md），驱动实现则以SyscallDrivertrait 呈现。

从源码印证：SyscallDrivertrait 定义于 kernel/src/syscall_driver.rs，约定command方法中命令 0 为保留命令，用于探测驱动是否安装，且必须返回CommandReturn::success；subscribe相关实现要求使用 upcall 的驱动必须为每个使用它的应用分配 grant 区域，以保证 Yield-WaitFor 场景下 upcall 可正常调度。

内核内部接口参考（doc/reference）

doc/reference/README.md 以Tock Reference Documents（TRD）形式记录内核内部 API，是内核开发者（特别是 HIL 设计者）的权威依据。当前收录：

• TRD 1：Tock 参考文档本身的定义与规范；
• TRD 102：ADC HIL；
• TRD 103：GPIO HIL；
• TRD 104：系统调用；
• TRD 105：Time HIL。

在doc/reference/中还存放着更多 HIL 与机制设计文档，例如 trd3-hil-design.md（HIL 设计原则，代码评审中要求新 HIL 遵循之）、trd101-time.md、trd-appid.md、trd-dynamic-process-loading.md 等。这些 TRD 与 doc/CodeGoals.md 的"重大变更须附 TRD"原则呼应：TRD 不仅记录设计，还记录设计背后的直觉、利弊与未采用的备选方案。

环境搭建与开发实践

从零开始搭建开发环境（doc/Getting_Started.md）

doc/Getting_Started.md 是 Tock 的上手指南，覆盖工具链安装、内核编译、硬件烧录与应用安装全流程。

极速上手（Super Quick Setup）——按平台执行：

• macOS：

  $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh $ pipx install tockloader $ pipx ensurepath

• Ubuntu：

  $ sudo apt install -y build-essential python3-pip curl $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh $ pipx install tockloader $ pipx ensurepath $ grep -q dialout <(groups $(whoami)) || sudo usermod -a -G dialout $(whoami) # 如需密码会提示重启

• Nix：直接执行$ nix-shell（仓库根目录提供 shell.nix）。

之后进入boards/<platform>目录运行make即可编译内核。

详细安装需要四类基础依赖：Rust、rustup（>= 1.23.0）、宿主工具链（gcc、glibc）、命令行工具（make、find）。当前仓库要求nightly-2026-07-21版本（由根目录 rust-toolchain.toml 固定），通过 rustup 安装以便多版本共存：

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh $ rustup install nightly-2026-07-21

安装后需source ~/.profile或重开 shell 使.cargo/bin进入$PATH。

编译内核：Tock 为每个板卡（board）构建唯一内核，板卡负责聚合正确的芯片与引脚配置。选择板卡后进入其目录，例如cd boards/nordic/nrf52840dk && make。所有板卡共享的常用 make 目标：

• all（默认）：编译该板卡的 Tock 内核；
• debug：生成带调试支持的构建（细节因板而异）；
• doc：为板卡构建文档；
• clean：清理该板卡构建产物；
• install：将内核烧录到板卡。

各板卡的详细说明见 boards/README.md 与各板卡子目录 README。

硬件与运行需要：一块受支持的板卡（或 QEMU 配置）、Tockloader、以及（多数板卡必需的）编程适配器。没有实体硬件时，Tock 提供有限的 QEMU 支持——boards/README.md 中标注了支持 QEMU 的板卡（如 QEMU RISC-V 32/64 位virt平台、HiFive1 等），并以make ci-job-qemu目标为 QEMU 支持与否的权威依据。

Tockloader是 Python 应用，负责把内核与应用烧录到板卡，并内置串口管理、以及通过 JTAG（或安装 bootloader 后的 USB）对应用进行 list/add/replace/remove 等操作：

$ pipx install tockloader $ pipx ensurepath

编程适配器有五种形态，可对照 boards/README.md 的 "Interface" 列选择：

1. Bootloader：板卡支持 Tock bootloader，无需额外适配器；
2. jLink：Segger 专有工具，需安装 "J-Link Software and Documentation Pack"，版本要求 >= 5.0；
3. openocd：自由软件适配器，要求 >= 0.10.0，安装方式：

   (Ubuntu): sudo apt-get install openocd (MacOS): brew install open-ocd (Fedora): sudo dnf install openocd

4. probe-rs：Rust 编写的编程与调试工具，安装见 probe-rs 官方安装文档 对应说明；
5. custom：板卡使用微控制器专属工具，见板卡 README。

烧录内核：进入tock/boards/<board>目录执行：

$ make install

各板卡的 Makefile（如 boards/nordic/nrf52840dk/ 内文件）中定义了默认烧录方式与可选方案。

安装应用：内核本身还不够"好玩"，可以用 Tockloader 一键安装示例 blink 应用：

$ tockloader install blink

Tockloader 会自动识别板卡、下载应用并烧录，成功后板卡 LED 会显示二进制计数器。若要自己编译应用，用户态代码分属两个仓库：C/C++ 应用（libtock-c）与 Rust 应用（libtock-rs），按各自 README 操作即可。

日常开发：仓库根目录运行$ make format可自动格式化全部 Rust 代码（基于 rustfmt.toml）；工具链升级由构建系统自动检测rustc/rustup版本并更新，安装好初始四项依赖后无需手动维护。

仓库结构与代码目标（doc/Repository.md、doc/CodeGoals.md）

doc/Repository.md 阐述了 Tock 仓库的主要代码目录分工，这是理解"文档对应代码在哪"的地图：

• arch/：架构相关代码（Cortex-M 各变体、RISC-V、x86 等），含上下文切换与系统调用陷入（如 arch/cortex-m/src/syscall.rs）；
• boards/：具体平台代码（imix、Hail、nrf52dk 等），核心文件是main.rs，其中with_driver函数定义系统调用设备标识符到 capsule 的映射；
• capsules/：与 MCU 无关的内核扩展（如 SPI capsule 基于芯片 SPI 实现向上提供 syscall）；
• chips/：微控制器专属代码（SPI、I2C、GPIO、UART 等具体实现）；芯片与板卡的区别在于"微控制器 vs 完整平台"——芯片提供 UART 实现，板卡决定哪个 UART 用于什么；
• kernel/：与 MCU 无关的内核核心（调度器、进程、内存管理），与 arch 一起构成全部核心内核代码；
• libraries/：Tock 内部使用也对外共享的库（如 tock-cells、tickv、riscv-csr、tock-tbf 等）；
• tools/：编译与维护辅助工具（格式检查、二进制转换、构建脚本）；
• vagrant/：在虚拟机环境中运行 Tock 的说明。

doc/CodeGoals.md 记录了 Tock 十余年形成的开发约定，是理解"为什么这样设计"的钥匙：

1. 支持已知与未知的多样用例：Tock 预期运行于多种硬件平台、满足多种需求，上游开发会在合理范围内权衡不同用例的利弊，某些贡献即使明显利好某一用例也可能需要更多审查；
2. 优先可维护性与长期代码：Tock 的价值观之一是精心设计，许多重大变更需附 TRD 记录设计直觉、利弊与备选方案，宁可数月合并也不草率推进；
3. 拥抱安全信条：Tock 自诞生即用 Rust，坚信内存安全检查与编译器安全收益，甚至在某些场景认为 Rust 过于宽松、期望更强保证，因此低层组件的贡献会接受更严格的审查。

嵌套板卡与树外板卡（doc/NestedBoards.md、doc/OutOfTree.md）

嵌套板卡（doc/NestedBoards.md）解决"硬件平台被其他硬件扩展（如扩展板、插接传感器）或作为其他平台基础"的场景。每个板卡是独立 crate，平台板卡成为依赖板卡的依赖；平台板卡 crate 同时是库与二进制，二进制几乎完全在库内实现，依赖板卡"继承"平台板卡全部功能并可实例化额外 capsule 进行扩展。其设计目标有三：普通板卡无需改动即可成为平台板卡；仅用标准 Rust/cargo 机制、无宏；依赖板卡的功能易于推演。由于 Rust 二进制 crate 不能作为依赖，平台板卡的Cargo.toml需同时声明库与二进制目标：

[package] name = "nrf52840dk" [lib] name = "nrf52840dk_lib" [[bin]] name = "nrf52840dk" path = "src/main.rs"

lib.rs暴露形如下方的start()函数，main.rs在加载进程、启动内核循环前调用它：

pub unsafe fn start() -> ( &'static kernel::Kernel, Platform, &'static nrf52840::chip::NRF52<'static, Nrf52840DefaultPeripherals<'static>>, &'static Nrf52DefaultPeripherals<'static>, );

树外板卡（doc/OutOfTree.md）指导维护不在 Tock master 中的子系统。要点：

• Tock 保证 syscall ABI 稳定，但不保证内核接口稳定，需通过 tock-dev 邮件列表与 Tock 的 PR 流程跟进开发动态；
• 建议镜像 Tock 目录结构（boards/my_board、capsules/等），代码置于独立 Cargo crate 中以便用 Cargo 引入依赖（含上游 Tock 内核 crate）；
• 板卡可先用 Cargo 构建（cargo build --release）；若想用 Make，需复制Makefile.common并在板卡目录编写 Makefile，定义program（bootloader 直连烧录）与flash（JTAG/外部编程器烧录）目标；
• 板卡Cargo.toml需通过 git 依赖引用 Tock 各 crate，并创建调用tock_build_scripts::default_linker_script()的build.rs；
• 链接脚本通过layout.ld定义内存映射并INCLUDE tock_kernel_layout.ld（该文件位于 boards/build_scripts/tock_kernel_layout.ld）；
• 自定义芯片/驱动只需一个 Cargo.toml；
• 示例项目包括 Signpost 项目的七个 Tock 板卡与早期的 STM32 移植。

代码风格与外部依赖政策（doc/Style.md、doc/ExternalDependencies.md）

doc/Style.md 明确 Tock 的代码风格约定：

• 格式：统一使用 rustfmt（遵循 rustfmt.toml）与 rustfmt 默认配置；
• 注释三类并用：//记录文件内部细节与作者等元数据；///为公开数据结构和函数提供 API 文档（每个公开函数/对象应有）；//!置于文件顶部概述文件内容，首行作为描述性标签行（一般不超过 80 字符），第二行留空//!以标识标签行；
• 命名：尽量避免缩写，使用描述性名称，例如ArrayIdx→ArrayIndex、BtnInterrupt→ButtonInterrupt、RegVoltOut→RegulatedVoltageOutput、GPIO.low_power()→GPIO.deactivate_and_make_low_power()。

doc/ExternalDependencies.md 定义 Tock 内核的外部依赖政策：总原则是内核不引入标准库之外的 Rust crate 外部依赖，但可在个案基础上、在适当保障下有限使用。政策按 crate 的反向依赖规模分层放宽：

• 内核 crate（kernel/）：零外部依赖；arch/、chips/、kernel/的外部依赖必须 vendor 进仓库；
• 板卡 crate（boards/）：最宽松，可用外部库（如无线协议实现，因时序与认证成本高）；
• capsule crate（capsules/）：capsules/core与capsules/extra必须零外部依赖，其余 capsule crate 可按需引入（如 BLE、TCP 等复杂子系统）；
• 依赖内部层级规则：板卡 crate 不被任何 Tock 内部 crate 依赖；芯片 crate 只被板卡或其他芯片 crate 依赖；capsule crate 只被其他 capsule 或板卡依赖；arch crate 只能依赖内核 crate 与其他 arch crate；内核 crate 不依赖 arch/chip/board/capsule。

选择外部依赖的通用准则：提供重要功能（如密码学库、syn/quote/proc-macro2过程宏支持）、项目可理解性（聚焦单一功能、代码高质量、只用标准 Rust 机制）、有限的子依赖树。唯一被批准的内核级例外是tock-registers（MMIO 寄存器接口，被 chips/ 广泛使用，独立仓库开发以鼓励更严格的向后兼容与定期发布）与flux-rs（基于 refinement types 的形式化验证，仅作可选依赖、只用于测试，不影响构建产物）。每个引入外部依赖的 crate 必须在 README 中增加 "External Dependencies" 小节，列出依赖及其树（可用cargo tree生成），并在 PR 描述中填写固定的四段式模板（Important Functionality / Project Maturity / Limited Sub-dependencies / Included as board or optional capsule）。

项目管理机制

工作小组（doc/wg）

doc/wg/README.md 介绍 Tock 的**工作小组（Working Groups）**体制：由于 Tock 子系统庞大且维护者难以跟进全部讨论，工作小组对特定子领域负责，成员成为该领域专家并决定贡献的审查力度、设计讨论频率等。结构上以Core Working Group为核心，外加领域小组：

• 核心工作小组：统筹项目全局，定义高层设计目标与方向，建立/解散工作小组，处理跨小组贡献冲突，并正式控制各 Tock 仓库的直接提交权；
• 领域工作小组：在各自子领域内拥有接收贡献、设计、方向的委派决策权，但成员不被期望成为主要贡献来源，而是建立审查标准、传达设计方向、支持贡献者。

组织准则：每个小组有 Lead；至少包含一名核心工作小组成员以保证信息同步；默认按共识决策、每周语音会议、公开会议记录、邮件列表异步沟通，也可自定规则。当前活跃小组：Core、OpenTitan、Network、Documentation、x86、Cryptography；已退休：Legacy。各小组详情见 doc/wg/core/README.md 等对应目录。

代码评审流程（doc/CodeReview.md）

doc/CodeReview.md 详细规定了主仓库的 PR 合并流程。PR 分为两类：

• Upkeep PR（维护型）：对现有实现的小改动（bug 修复、非规格文档、小型重实现）。又细分为极微小（错别字/格式/clippy）、微小（少量行改动、Tier 2/3 板卡功能等）、中等（新 capsule、内核 crate 小改、Tier 1 板卡改动、HIL 实现等）；
• Significant PR（重大型）：新模块、重大重实现、新 trait、新内核组件或构建系统变更，需全体核心团队在一周内回复 Accept / No Comment / Discuss。

CI 体系全部由 make 规则驱动：make prepush是提交 PR 前应本地运行的"标准开发者 CI"元目标；细粒度测试规则统一放在ci-job-*中（不做一次性设置操作）；ci-setup-*负责安装依赖（应缓存结果、本地运行时系统级变更必须提示）；ci-runner-*精确对应各 CI runner 执行内容且须能在本地复现；ci-all运行全部 CI。评审原则强调：unsafe代码必须附 Safety 注释（含调用方不变量模板、trait 方法实现与代码块三种模板）、回调只能在中断中发出（不可从 downcall 直接回调）、static_init!()只能出现在板卡 crate、敏感导出须用 capability 保护等。合并要求两个 Accept 且无 Discuss；unsafe评审还按仓库子系统（kernel/HIL/capsules/chips/boards/arch/libraries）给出专项指南，例如新 HIL 应遵循 TRD 3、syscall 驱动须支持多进程访问且command_id==0返回成功、chip 外围必须实现至少基础功能方可合并等。

发布与驱动稳定化（doc/Maintenance.md）

doc/Maintenance.md 描述核心工作小组的维护职责，重点是里程碑式发布策略（约每 3-12 个月一个版本，替代早期每两个月的时间制发布）：

1. 发布前：决定包含的功能，给相关 issue/PR 打release-blocker标签，开启 "Release " 跟踪 issue（含目标清单、逐板卡测试模板、核心成员签核清单），逐项关闭 release-blocker；
2. 发布测试：在release/$major.$minor发布分支上逐板卡测试——从上一版本跟踪 issue 复制并取消勾选测试清单、认领板卡、补充新测试，失败项在 issue 评论中标记X并描述失败方式，随后提交修复 PR 或发布求助 issue；必要时可打发布候选（release candidate）标签；
3. 打标签：所有板卡测试通过、更新 CHANGELOG、将 kernel/src/lib.rs 中KERNEL_PRERELEASE_VERSION置 0、更新根目录 Cargo.toml 版本号后，以注解标签（annotated tag，git tag -a）按release-$major.$minor.$patch格式打标签（首个 minor 版本 patch 为 0）；
4. 开启下一轮：branch 切出后立即在 master 上递增 minor 号、patch 置 0（根 Cargo.toml 设为<new version>-dev，kernel/src/lib.rs 更新KERNEL_MAJOR/MINOR/PATCH_VERSION并将KERNEL_PRERELEASE_VERSION置 1）。

Syscall 驱动稳定化是 Tock 的核心兼容性承诺：稳定后的驱动在同 major 版本内保证不破坏，使用该驱动的应用在同 major 内核上持续可用（但允许在同一 major 内扩展接口、加功能或修 bug）。流程为：

1. 驱动在doc/syscalls/有完整文档；
2. 开发者提交 PR 将驱动移入capsules/corecrate，并在 doc/syscalls/README.md 稳定列标记 ⏰；
3. 稳定化 PR 恒为P-Significant，需核心工作小组支持；
4. 驱动接口须保持四个月不变（期间合理测试，可回溯起算），若需修改则等待期重置；
5. 缓刑期结束后，在下一个 major/minor 发布时将稳定列更新为该发布版本号。

对照 doc/syscalls/README.md 的表格，可见 Alarm、Console、LED、Button、ADC、Ambient Temp.、Humidity、Luminance 等已标 ✓ 稳定，而 GPIO、IPC、DBS 等仍处于未稳定状态——这正是该流程落地执行的直接证据。

安全漏洞处理流程（doc/SecurityProtocol.md）

doc/SecurityProtocol.md 定义安全漏洞的内部处理流程，角色分工明确：Triage Coordinator负责 5 天内初审、分类、指派、协调响应团队、与利益相关方沟通并跟踪解决进度；Security Response Team由各子系统维护者组成。子系统联系人表（Kernel、Drivers、libtock-c、libtock-rs、Build、ARM、RISC-V、x86 等均配有主/备联系人）确保漏洞能直达对应专家。

漏洞处理六阶段：

1. 接收与初审（5 天）：漏洞统一经security@lists.tockos.org接收；回执确认并分配唯一 ID（uuidgen | cut -d'-' -f1生成，如C2C47E9A）；评估严重性（Critical/High/Medium/Low）、受影响组件与优先级（P0-P3）；有效漏洞创建私有 GitHub Security Advisory；
2. 指派与响应规划（5 天-1 周）：指派给子系统维护者，必要时建立响应团队频道，按严重性定义解决时间线，秘密通知利益相关方；
3. 修复开发：私下开发并测试修复、彻底代码评审、验证无新问题、内部记录、准备披露说明；
4. 公开披露准备：确定披露日期，准备完整公告（详细描述、受影响版本、缓解措施、升级指引、报告者致谢），发布安全公告与修补版本；
5. 发布与披露：合并修复到主分支、发布修补版本、发布公告，并通知安全公告邮件列表、报告者与利益相关方，更新公开文档；
6. 披露后活动：监控修复效果、进行复盘、更新文档。

文档还附有三套通信模板（初始回执、状态更新、披露通知）以及 GitHub Security Advisories、私有邮件列表等工具资源，供处理者直接套用。

如何在文档迷宫中继续深入

面对 Tock 庞大的文档与源码，建议的导航路径是：

1. 先读 doc/README.md建立全局地图，明确当前需求属于接口、开发还是管理范畴；
2. 用户态开发从 doc/syscalls/README.md 的驱动号表入手，找到目标驱动号后阅读doc/syscalls/下对应规格文件，再对照capsules/中该驱动的SyscallDriver实现；
3. 内核开发从 doc/reference/README.md 的 TRD 入手，理解 HIL 设计后，在kernel/src/hil/与chips/、arch/中查看具体实现，并遵循 doc/CodeReview.md 的子系统评审指南；
4. 环境与板卡以 doc/Getting_Started.md 为操作手册，以 boards/README.md 的板卡矩阵（Tier 1/2/3 与 Other，含架构、MCU、烧录接口、QEMU 支持）为选型依据；
5. 贡献与治理对照 doc/CodeGoals.md、doc/Style.md、doc/ExternalDependencies.md、doc/Maintenance.md 与 doc/SecurityProtocol.md，确保贡献符合项目长期演进方向。

这套文档体系与仓库源码同库演进、互相印证——规格文件定义契约，TRD 记录设计理性，源码实现落地行为，管理文档约束流程，共同构成 Tock 作为安全嵌入式操作系统"可审计、可维护、可长期演进"的工程基础。

• 操作系统
• 嵌入式
• 嵌入式OS