Merge pull request #3 from Awesome-Embedded-Learning-Studio/docs/vitepress-site

docs: VitePress 文档站点 + GitHub Pages 自动部署

Author: Charliechen114514

.github/workflows/deploy.yml

@@ -0,0 +1,42 @@
+name: Deploy VitePress
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site/.vitepress/dist

.gitignore

@@ -75,4 +75,11 @@ compile_commands.json
 !**/.gitkeep
 
 *.bin
-*.img
+*.img
+
+# --- VitePress 文档站点 ---
+node_modules/
+site/.vitepress/dist/
+site/.vitepress/cache/
+site/.vitepress/.temp/
+*.tgz

document/README.md

@@ -9,7 +9,7 @@ rk-forge 的文档分四层,各司其职。原始过程素材(raw 笔记 + 板
 | 教程 | [tutorial/](tutorial/) | 面向外部读者:结论性 how-to(成功路径)。每章"成功长这样"配真实 UART 抓取。 |
 | 踩坑日记 | [pitfalls/](pitfalls/) | 按**故障域分篇**(4 篇),还原真实时间线 + 弯路 + 被推翻的结论 + 每步板上 log 佐证,覆盖 12 条坑。 |
 | 过程笔记 | [notes/](notes/) | raw dated bringup 日记(含失败、噪音、半成品),honesty substrate,是踩坑日记的取证源。 |
-| 归档 | [archive/](archive/) | 被证伪/取代的旧结论文档,带 superseded banner + canonical 指针,保留"走过的错路"但不误导。 |
+| 归档 | `archive/` | 被证伪/取代的旧结论文档,带 superseded banner + canonical 指针,保留"走过的错路"但不误导。 |
 | 参考 | [sdk-diff.md](sdk-diff.md) | vendor SDK vs 主线移植的逐外设差距对照(活文档)。 |
 
 ## 板上日志(取证素材)

document/index.md

@@ -0,0 +1,47 @@
+---
+layout: home
+
+hero:
+  name: "RK-Forge"
+  text: "RK3506 主线优先开发工作空间"
+  tagline: 面向 Rockchip RK3506，从工具链到 rootfs、外设、SD 启动的完整主线学习路径——别人卖成品镜像，我们卖菜谱 + 灶 + 带你做饭的书
+  image:
+    src: /Awesome-Embedded.png
+    alt: RK-Forge Logo
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /tutorial/boot/
+    - theme: alt
+      text: 教程目录
+      link: /tutorial/
+    - theme: alt
+      text: GitHub
+      link: https://github.com/Awesome-Embedded-Learning-Studio/rk-forge
+
+features:
+  - icon: 🚀
+    title: 主线优先
+    details: 主线 Linux 7.1 + U-Boot 2026.07-rc4，紧跟上游；RK-SDK 整个坍缩成 rkbin + 一块板级设备树
+    link: /tutorial/boot/
+  - icon: 🧩
+    title: 有序补丁库
+    details: quilt 风格 series，git am 落真实 commit、可 bisect、失败原子回滚——修掉"只打最后一个补丁"的老毛病
+    link: /tutorial/boot/
+  - icon: 📋
+    title: 诚实的差距报告
+    details: 逐子系统告诉你 vendor BSP 有什么 / 主线有什么 / 差什么 / 还能不能 boot，绝不藏着
+    link: /sdk-diff
+  - icon: 📖
+    title: 0→1 教程
+    details: 从空机器到 RK3506 主线启动到 UART 登录的可复现路径，每章配真实板上抓取，绝不合成
+    link: /tutorial/
+  - icon: 🛠️
+    title: forge 编排器
+    details: 把 kernel / uboot / rootfs 一长串命令收成一个 setup→build→pack→assemble 编排器，DAG + 增量跳过
+    link: /tutorial/forge/
+  - icon: 💾
+    title: 双启动路径
+    details: SPI-NAND（UBIFS）+ SD 卡（RKFW）两条启动路都板上验证通过，含 loader 弱写 saga 的根治解
+    link: /tutorial/sd-boot/
+---

document/logs/README.md

@@ -1,6 +1,6 @@
 # document/logs/ — 板上取证日志
 
-这里 47 个文件,全是 RK3506B 真板上电实跑的原始 UART 抓取加构建日志,没有一个是合成的。它们是 [pitfalls/](../pitfalls/) 和 [notes/](../notes/) 里那些"成功长这样""失败长那样"的底气——每个结论背后都能翻出一行对应的串口原文。
+这里近百个文件,全是 RK3506B 真板上电实跑的原始 UART 抓取加构建日志,没有一个是合成的。它们是 [pitfalls/](../pitfalls/) 和 [notes/](../notes/) 里那些"成功长这样""失败长那样"的底气——每个结论背后都能翻出一行对应的串口原文。
 
 ## 命名约定
 

document/logs/index.md

@@ -0,0 +1,16 @@
+---
+title: 板上日志
+---
+
+<PageHeader icon="📟" title="板上日志" description="真实 UART 抓取 + 构建日志——笔记与踩坑日记「绝不合成」承诺的底气" />
+
+这里（`document/logs/`）是近百个真实的板上 UART 抓取 + 构建日志，是笔记和踩坑日记"绝不合成"承诺的底气。每个里程碑 log 对应佐证哪个坑，完整索引见 [logs/README](./README)。
+
+> 这些 `.txt` 是原始串口 / 构建输出，站点上点开会在 GitHub 上查看（原样保留，不渲染）。
+
+### 里程碑 log（近 → 远）
+
+- [boot-sdl-202606211028.txt](boot-sdl-202606211028.txt) — SD 卡纯 ext4 启动收官（kernel + rootfs 都从 SD 起，无 ubi/panic）
+- [boot-sdl-202606201050.txt](boot-sdl-202606201050.txt) — WiFi RTL8733BU 板上全链验证
+- [boot-sdl-2026-06211109.txt](boot-sdl-2026-06211109.txt) — 全链主线启动到 `rk3506 login:`
+- [boot-sdl-202606182049.txt](boot-sdl-202606182049.txt) — buildroot 最小 rootfs 首启到 login

document/notes/02-2026-06-14-mainline-bringup-handoff.md

@@ -94,7 +94,7 @@ boot 链:SPL → 装 optee(0x1000)+uboot(0x200000)+fdt → 跳 optee(安全世
 
 **地址坑(关键)**:主线 `CONFIG_TEXT_BASE=0x00800000`,vendor FIT 里 uboot@0x00200000,差 6MB。我们代码按 0x800000 链接,装到 0x200000 会崩(绝对寻址错)。**解法:ITS 里 uboot `load=0x00800000`**(匹配我们编译),optee(0x1000)/tee 不动。SPL 装我们 uboot 到 0x800000,optee NS 跳转地址由 SPL 按 loadable 的 load 设置 → 自洽。
 
-**产物**:`third_party/bringup/fit/rk3506-mainline.its`(手写,复刻 vendor 结构)+ `rk3506-mainline.itb`(547KB,vendor 2017.09 mkimage `-E` 打包)。dumpimage 对照:optee hash 值与 vendor **逐字节相同**(同一颗 tee.bin),结构/conf 全对。Windows 副本:`D:\DownloadFromInternet\rk3506-uboot-mainline-vendor-fit.itb`。
+**产物**:`board/aes/fit/rk3506-mainline.its`(手写,复刻 vendor 结构)+ `rk3506-mainline.itb`(547KB,vendor 2017.09 mkimage `-E` 打包)。dumpimage 对照:optee hash 值与 vendor **逐字节相同**(同一颗 tee.bin),结构/conf 全对。Windows 副本:`D:\DownloadFromInternet\rk3506-uboot-mainline-vendor-fit.itb`。
 
 **烧板(待用户操作,RKDevTool "下载镜像"模式)**:
 1. Loader = `rk3506-vendor-loader.bin`(vendor 原装,恢复 vendor SPL 到 boot 区 + 进下载模式)
@@ -119,7 +119,7 @@ boot 链:SPL → 装 optee(0x1000)+uboot(0x200000)+fdt → 跳 optee(安全世
 方案 B(借 vendor SPL/DDR/usbplug,主线 U-Boot proper 走 vendor 格式 FIT)已**完整跑通**。boot 链:`bootrom → vendor idblock(vendor DDR v1.06 + vendor SPL 2017) → 读 NAND uboot 分区(我们 FIT) → 装 optee(0x1000)+uboot(0x800000)+fdt → OP-TEE → NS 跳 0x800000 → 主线 U-Boot 2026.07-rc4 提示符`。
 
 **关键产出(可复用)**:
-- `third_party/bringup/fit/rk3506-mainline.its` + `rk3506-mainline.itb`(vendor 格式 FIT 模板,uboot load=0x800000)
+- `board/aes/fit/rk3506-mainline.its` + `rk3506-mainline.itb`(vendor 格式 FIT 模板,uboot load=0x800000)
 - `arch/arm/dts/rk3506.dtsi` 加 OTP 节点(ff4f0000)
 - Windows:`D:\DownloadFromInternet\rk3506-uboot-mainline-vendor-fit.itb` + `rk3506-vendor-loader.bin`
 

document/notes/04-2026-06-14-mainline-uboot-via-vendor-spl.md

@@ -97,7 +97,7 @@ vendor 的 `tee.bin` 是 rkbin 预编译 blob,源码不在手,**无法事先确
 - `fdt` 节点:`data` 指向我们的 `u-boot.dtb`(rk3506-evb)。
 - `optee` 节点:`data` 指向 vendor `tee.bin`,`load/entry = <0x00001000>` 不动。
 
-放新目录 `third_party/bringup/fit/`,三个 blob 汇聚进去(uboot-nodtb.bin / u-boot.dtb / tee.bin),ITS 用相对文件名自包含。
+放新目录 `board/aes/fit/`,三个 blob 汇聚进去(uboot-nodtb.bin / u-boot.dtb / tee.bin),ITS 用相对文件名自包含。
 
 ### mkimage 选型
 用 **vendor 的 `tools/mkimage`(2017.09)** 打包,而不是主线的。理由:与 vendor SPL 字节级兼容(同源工具),`-E` external data 模式是 RK SPL 的读取约定。
@@ -272,9 +272,9 @@ Scanning for bootflows in all bootdevs
 ### 新产出物
 | 路径 | 内容 |
 |---|---|
-| `third_party/bringup/fit/rk3506-mainline.its` | 手写的 vendor 格式 FIT 源(可复用模板) |
-| `third_party/bringup/fit/rk3506-mainline.itb` | 打包好的 vendor 格式 FIT(547 KB) |
-| `third_party/bringup/fit/{uboot-nodtb.bin,u-boot.dtb,tee.bin}` | 三方汇聚的 blob |
+| `board/aes/fit/rk3506-mainline.its` | 手写的 vendor 格式 FIT 源(可复用模板) |
+| `board/aes/fit/rk3506-mainline.itb` | 打包好的 vendor 格式 FIT(547 KB) |
+| `board/aes/fit/{uboot-nodtb.bin,u-boot.dtb,tee.bin}` | 三方汇聚的 blob |
 
 ### Windows 侧(给 RKDevTool 烧板用,`D:\DownloadFromInternet\`)
 | 文件 | 角色 |

document/notes/05-2026-06-15-nand-boot-bbm-ecc-debug.md

@@ -74,11 +74,11 @@ RK=third_party/explore/rkbin/bin/rk35
 make ARCH=arm CROSS_COMPILE=$TC -j$(nproc) ROCKCHIP_TPL=$RK/rk3506b_ddr_750MHz_v1.06.bin TEE=$RK/rk3506_tee_v2.40.bin
 
 # 打包方案 B FIT:
-cp u-boot-nodtb.bin u-boot.dtb third_party/bringup/fit/
-(cd third_party/bringup/fit && ../../vendor-sdk/u-boot/tools/mkimage -f rk3506-mainline.its -E rk3506-mainline.itb)
+cp u-boot-nodtb.bin u-boot.dtb board/aes/fit/
+(cd board/aes/fit && ../../vendor-sdk/u-boot/tools/mkimage -f rk3506-mainline.its -E rk3506-mainline.itb)
 
 # 拷 Windows:
-cp third_party/bringup/fit/rk3506-mainline.itb /mnt/d/DownloadFromInternet/rk3506-uboot-mainline-vendor-fit.itb
+cp board/aes/fit/rk3506-mainline.itb /mnt/d/DownloadFromInternet/rk3506-uboot-mainline-vendor-fit.itb
 ```
 
 ## 当前状态(2026-06-15)
@@ -92,6 +92,6 @@ cp third_party/bringup/fit/rk3506-mainline.itb /mnt/d/DownloadFromInternet/rk350
 
 - U-Boot spinand driver: `third_party/explore/uboot/drivers/mtd/nand/spi/core.c`
 - W25N04KV 配置: `third_party/explore/uboot/drivers/mtd/nand/spi/winbond.c:483`
-- 内核 FIT: `third_party/bringup/fit/rk3506-kernel.itb`(+ `.its`)
-- U-Boot FIT(方案 B): `third_party/bringup/fit/rk3506-mainline.itb`
+- 内核 FIT: `board/aes/fit/rk3506-kernel.itb`(+ `.its`)
+- U-Boot FIT(方案 B): `board/aes/fit/rk3506-mainline.itb`
 - 上板日志: `document/logs/boot-sdl-202606150723.txt`(mtd read corrupt)、`uboot-debug.txt`(dump)

document/notes/06-2026-06-15-nand-recovery-vendor-sfc-bbt.md

@@ -60,6 +60,6 @@ w: LBA=cd00 PBA=cd00 is bad block skip0                          ← vendor 判
 
 - corrupt 问题完整现状: [nand-ecc-debug-handoff.md](nand-ecc-debug-handoff.md)
 - U-Boot spinand driver: `third_party/explore/uboot/drivers/mtd/nand/spi/core.c`
-- 当前稳定版 U-Boot FIT: `third_party/bringup/fit/rk3506-mainline.itb`(md5 5520bc46)
-- 内核 FIT: `third_party/bringup/fit/rk3506-kernel.itb`
+- 当前稳定版 U-Boot FIT: `board/aes/fit/rk3506-mainline.itb`(md5 5520bc46)
+- 内核 FIT: `board/aes/fit/rk3506-kernel.itb`
 - 上板日志(恢复后): 本篇上面的输出(含 vendor SFC bad block 扫描)