清理存量 ASCII 框图：存储栈/分区转 SVG、CH395F 时序转 Mermaid

2026-09-11 23:01:25 +08:00
parent d150810587
commit 7e527fa04d
8 changed files with 443 additions and 106 deletions
@@ -52,14 +52,6 @@ RemoDispBus 让远端（PC 上的 DTU-RemoteLCD 客户端 / 浏览器页面）
 | 4 | `DATA` | `LEN` | 数据段（命令相关，见 §1.5） |
 | 4+LEN | `CRC` | 1 | 数据段逐字节异或（低 8 位） |

-```
-┌───────┬───────┬─────────┬─────────┬───────────┬───────┐
-│ TAG │ CMD │ LEN_H │ LEN_L │   DATA    │ CRC │
-├───────┼───────┼─────────┼─────────┼───────────┼───────┤
-│ 1 B │ 1 B │  1 B  │  1 B  │   LEN B   │ 1 B │
-└───────┴───────┴─────────┴─────────┴───────────┴───────┘
-```
-
 - 整帧长度 = `4 + LEN + 1`；`LEN=0` 时最短为 5 字节。
 - `LEN` 为 16 位大端，理论最大 65535 数据字节。

@@ -4,38 +4,13 @@

 本 项目在 GD5F2GQ5UE SPI NAND Flash（256MB）上实现了三层存储软件栈：

-```
-┌─────────────────────────────────────────────────────────────┐
-│                    应用程序 (main, freertos)                  │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│                         FatFs (文件系统)                      │
-│                                                              │
-├─────────────────────────────────────────────────────────────┤
-│                      dhara FTL                                │
-│  (地址映射 · 磨损均衡 · 坏块管理 · 垃圾回收)                  │
-├─────────────────────────────────────────────────────────────┤
-│              GD5F2GQ5UE NAND Flash 驱动 (底层 SPI)           │
-│    硬件 SPI · 页读写 · 块擦除 · BBT · 内部 ECC 使能          │
-├─────────────────────────────────────────────────────────────┤
-│              SPI1 硬件外设 (PB3 SCK, PB4 MISO, PB5 MOSI)     │
-│       42MHz · Mode 0 · MSB First · DMA2 (S0-RX, S3-TX)      │
-│       小包轮询(≤32B) · 页数据 DMA (>32B)                    │
-└─────────────────────────────────────────────────────────────┘
-```
+![存储软件栈分层（应用 → FatFs → dhara FTL → 驱动 → SPI1）](images/存储栈分层.svg)

-```
-┌─────────────────────────────────────────────────────────────┐
-│                     物理分区布局 (256MB)                      │
-│                                                              │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │  ftl_fatfs (256MB)                                       │  │
-│  │  Block 0~2047                                            │  │
-│  │  dhara FTL + FatFS（全部 2048 个块）                      │  │
-│  └──────────────────────────────────────────────────────────┘  │
-│  偏移: 0                                                 256MB│
-└─────────────────────────────────────────────────────────────┘
-```
+> 上图由 `tools/arch_diagram/gen_storage_stack_svg.py` 生成（手绘 SVG，布局确定、层间单向箭头）；改分层后编辑脚本顶部 `L_*` / `ROWS` 数据重跑即可。
+
+![物理分区布局（256MB 单分区）](images/物理分区布局.svg)
+
+> 上图由 `tools/arch_diagram/gen_partition_svg.py` 生成（分区宽 ∝ MB 数 + 偏移标尺）；改分区后编辑脚本顶部 `FIELDS` 数据重跑即可。

 **数据路径：**
 - **应用** → `FatFS` → `dhara FTL` → `gd5f2gq5ue 驱动`。FTL 提供 LBA 到物理页的映射、磨损均衡、坏块管理和垃圾回收，FatFS 通过标准 `disk_*` 接口访问 FTL 提供的块设备。
@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="528" viewBox="0 0 1000 528" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
+<rect x="0" y="0" width="1000" height="528" fill="#ffffff"/>
+<text x="26" y="40" font-size="20" font-weight="700" fill="#0f172a">STM32F4-Base 存储软件栈</text>
+<text x="26" y="62" font-size="13" fill="#64748b">GD5F2GQ5UE SPI NAND Flash（256MB）· 三层软件栈（FatFs / dhara FTL / 驱动）· 上层只依赖相邻下层</text>
+<rect x="26" y="78" width="948" height="44" rx="12" fill="#eff6ff" stroke="#2563eb" stroke-opacity="0.45"/>
+<text x="44" y="104" font-size="17" font-weight="700" fill="#2563eb">应用程序</text>
+<text x="124" y="104" font-size="12" fill="#64748b">main · freertos（CubeMX 生成 + FreeRTOS 任务）</text>
+<rect x="26" y="166" width="948" height="44" rx="12" fill="#f0fdfa" stroke="#0d9488" stroke-opacity="0.45"/>
+<text x="44" y="192" font-size="17" font-weight="700" fill="#0d9488">FatFs</text>
+<text x="105" y="192" font-size="12" fill="#64748b">文件系统（标准 disk_* 块设备接口）</text>
+<rect x="26" y="254" width="948" height="44" rx="12" fill="#f0fdf4" stroke="#16a34a" stroke-opacity="0.45"/>
+<text x="44" y="280" font-size="17" font-weight="700" fill="#16a34a">dhara FTL</text>
+<text x="145" y="280" font-size="12" fill="#64748b">地址映射 · 磨损均衡 · 坏块管理 · 垃圾回收</text>
+<rect x="26" y="342" width="948" height="44" rx="12" fill="#fffbeb" stroke="#d97706" stroke-opacity="0.45"/>
+<text x="44" y="368" font-size="17" font-weight="700" fill="#d97706">GD5F2GQ5UE NAND Flash 驱动</text>
+<text x="307" y="368" font-size="12" fill="#64748b">硬件 SPI · 页读写 · 块擦除 · BBT · 内部 ECC 使能</text>
+<rect x="26" y="430" width="948" height="44" rx="12" fill="#fff1f2" stroke="#e11d48" stroke-opacity="0.45"/>
+<text x="44" y="456" font-size="17" font-weight="700" fill="#e11d48">SPI1 硬件外设</text>
+<text x="173" y="456" font-size="12" fill="#64748b">PB3 SCK · PB4 MISO · PB5 MOSI · 42MHz · Mode 0 · MSB First · DMA2（S0-RX / S3-TX）· 小包轮询（≤32B）/ 页数据 DMA（&gt;32B）</text>
+<line x1="500.0" y1="128.0" x2="500.0" y2="151.0" stroke="#94a3b8" stroke-width="2.5"/>
+<path d="M 500.0 158.0 l -6 -9 h 12 z" fill="#94a3b8"/>
+<line x1="500.0" y1="216.0" x2="500.0" y2="239.0" stroke="#94a3b8" stroke-width="2.5"/>
+<path d="M 500.0 246.0 l -6 -9 h 12 z" fill="#94a3b8"/>
+<line x1="500.0" y1="304.0" x2="500.0" y2="327.0" stroke="#94a3b8" stroke-width="2.5"/>
+<path d="M 500.0 334.0 l -6 -9 h 12 z" fill="#94a3b8"/>
+<line x1="500.0" y1="392.0" x2="500.0" y2="415.0" stroke="#94a3b8" stroke-width="2.5"/>
+<path d="M 500.0 422.0 l -6 -9 h 12 z" fill="#94a3b8"/>
+<text x="26" y="510" font-size="12" fill="#94a3b8">数据路径：应用 → FatFs → dhara FTL → gd5f2gq5ue 驱动 → SPI1 硬件外设（单向依赖）· 详见 docs/STM32F4-Base存储架构说明.md §1</text>
+</svg>
@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1104" height="246" viewBox="0 0 1104 246" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
+<rect x="0" y="0" width="1104" height="246" fill="#ffffff"/>
+<text x="40" y="40" font-size="20" font-weight="700" fill="#0f172a">GD5F2GQ5UE 物理分区布局（256MB）</text>
+<text x="40" y="64" font-size="13" fill="#64748b">单分区：全片划给 FTL（无静态分区）· 块 = 128KB（64 页 × 2KB）· 共 2048 块</text>
+<line x1="40" y1="96" x2="1064" y2="96" stroke="#cbd5e1" stroke-width="1"/>
+<line x1="40" y1="92" x2="40" y2="100" stroke="#94a3b8" stroke-width="1.5"/>
+<text x="40" y="88" font-size="12" fill="#94a3b8" text-anchor="middle">0</text>
+<line x1="1064" y1="92" x2="1064" y2="100" stroke="#94a3b8" stroke-width="1.5"/>
+<text x="1064" y="88" font-size="12" fill="#94a3b8" text-anchor="middle">256 MB</text>
+<rect x="40" y="116" width="1024" height="74" fill="#eff6ff" stroke="#2563eb" stroke-width="1.5"/>
+<text x="552.0" y="146" font-size="15" font-weight="700" fill="#0f172a" text-anchor="middle">ftl_fatfs</text>
+<text x="552.0" y="170" font-size="12" fill="#2563eb" text-anchor="middle">256 MB · Block 0~2047</text>
+<text x="40" y="230" font-size="12" fill="#94a3b8">ftl_fatfs：dhara FTL + FatFS 占用全部 2048 块（偏移 0 ~ 256MB）· 详见 docs/STM32F4-Base存储架构说明.md §1</text>
+</svg>
@@ -12,7 +12,8 @@
 | 图形类型 | 工具 | 说明 |
 |---|---|---|
 | 协议帧 / 字节布局（精确比例） | **SVG**（`gen_frame_svg.py`） | 字段宽须严格 ∝ 字节数 + 逐字段标注 + 偏移标尺 |
-| 分层架构 / 模块依赖 | **SVG**（`gen_arch_svg.py`） | 多节点跨层依赖，Mermaid 会画成"意大利面"，手工排布更清晰 |
+| 闪存 / 内存分区布局（精确比例） | **SVG**（`gen_partition_svg.py`） | 帧图生成器的 MB 计量副本（分区宽 ∝ MB 数 + 偏移标尺） |
+| 分层架构 / 模块依赖 | **SVG**（`gen_arch_svg.py`） | 多节点跨层依赖，Mermaid 会画成"意大利面"，手工排布更清晰；单层单职责的栈图用其副本 `gen_storage_stack_svg.py` |
 | 就绪屏障 / 生产者-消费者 | **SVG**（`gen_barrier_svg.py`） | 三栏对齐 + 正交连线，避免交叉 |
 | 流程图 / 时序 / 状态机 / ER | **Mermaid**（Markdown 内嵌） | 拓扑关系类图，节点少、强调连接；渲染器原生支持 |
 | UI 界面 / 像素级样机 | `simulator/` 截图、`tools/ui_mock/` | 非本流程范围 |
@@ -41,6 +42,8 @@
 | `gen_arch_svg.py` | `docs/images/项目架构总览.svg` | `LAYERS` / `ROWS` / `FOOT` |
 | `gen_barrier_svg.py` | `docs/images/就绪屏障.svg` | `BITS` / `PRODUCERS` / `CONSUMERS` |
 | `gen_frame_svg.py` | `docs/images/RemoDispBus帧格式.svg` | `FIELDS` / `TITLE` / `SUB` / `FOOT` |
+| `gen_storage_stack_svg.py` | `docs/images/存储栈分层.svg` | `L_*` / `ROWS` / `TITLE` / `SUB` / `FOOT` |
+| `gen_partition_svg.py` | `docs/images/物理分区布局.svg` | `FIELDS` / `TITLE` / `SUB` / `FOOT`（MB 计量） |

 ---

@@ -131,3 +134,4 @@ sequenceDiagram
 |---|---|
 | 2026-09-11 | 创建：统一图形绘制流程（选型 / SVG 生成器 / Mermaid / 约定 / 检查清单）；新增 `tools/arch_diagram/gen_frame_svg.py`（通用协议帧图）+ `docs/RemoDispBus帧格式.svg` |
 | 2026-09-11 | 新增专门配图目录 `docs/images/`：收拢 `docs/` 根与 `docs/UI 设计/images/` 下 5 张 SVG；同步更新 3 个生成器 OUT 路径、4 处文档图片引用、`AGENTS.md` 与 `.gitignore`（PNG 预览规则）；流程沉淀为 `draw-diagram` skill |
+| 2026-09-11 | 存量 ASCII 框图清理：`STM32F4-Base存储架构说明.md` 两图（存储栈分层 / 物理分区布局）重绘为 SVG（生成器家族新增 `gen_storage_stack_svg.py` / `gen_partition_svg.py`）；`RemoDispBus协议与接收设计说明.md` 删 ASCII 帧图（SVG 帧格式图已在，信息无损失）；`测试说明/CH395F_Test_Guide.md` 4 图（2 组件架构 + 2 会话时序）转 Mermaid |
@@ -522,46 +522,35 @@ MCU (TCP Client, ch395f_* 裸命令)          PC (tcp_bulk --port 8081)

 **架构图（组件）**：

-```
-┌──────────────┐                    TCP 8080                    ┌──────────────────────────┐
-│   PC (Python) │ ───────────────────────────────────────────▶ │  CH395F (192.168.1.100)  │
-│ tcp_client /  │                  Ethernet                     │  Socket 0（单连接复用）   │
-│ tcp_server    │              (SPI2, 分频=8)                   └────────────┬─────────────┘
-└──────────────┘                                                    SPI    │
-                                                                          ▼
-                                                            ┌──────────────────────────┐
-                                                            │      MCU (STM32F407)      │
-                                                            │ netTask: net_poll() 10ms  │
-                                                            │ testTask:                 │
-                                                            │  net_layer_test_main()    │
-                                                             │   └─ phase6_run() 原样回显 │
-                                                            └──────────────────────────┘
+```mermaid
+flowchart LR
+    PC["PC（Python）<br/>tcp_client / tcp_server"] -->|"TCP 8080 · 以太网"| CH["CH395F（192.168.1.100）<br/>Socket 0（单连接复用）"]
+    CH -->|"SPI2（分频=8）"| MCU["MCU（STM32F407）<br/>netTask: net_poll() 10ms<br/>testTask: net_layer_test_main()<br/>└─ phase6_run() 原样回显"]
 ```

 **会话时序图（单连接生命周期）**：

-```
- PC (Client)              CH395F Socket 0                MCU testTask
-     │                          │                            │
-     │   SYN ──────────────────▶│                            │
-     │◀──────────────── SYN+ACK │                            │
-     │   ACK ──────────────────▶│  ESTABLISHED              │
-     │                          │── 中断/GlobInt ───────────▶│ net_poll()
-     │                          │                            │ net_accept()→phase_active
-     │  [64B 数据] ───────────▶│  recv_len = N              │
-     │                          │── 中断 ───────────────────▶│ net_poll()
-     │                          │                            │ phase6_run():
-     │                          │                            │   net_recv(N) → 字节校验
-     │                          │                            │   TEST_CHECK(累加和)
-     │◀──────────── [64B 回显]─│  net_send()                │
-     │  (逐字节比对 + 累加和)    │                            │
-     │     (重复 N 轮 / 多包)    │                            │
-     │                          │                            │
-      │  FIN/RST ───────────────▶│  DISCONNECT                │
-      │                          │── 中断 ───────────────────▶│ net_poll()
-      │                          │                            │ net_recv EOF → auto_relisten
-      │                          │◀─ 自动 OPEN + TCP_LISTEN   │
-      │  SYN(新连接) ───────────▶│  LISTEN 自动恢复，重新接受 │
+```mermaid
+sequenceDiagram
+    participant C as PC（Client）
+    participant S as CH395F Socket 0
+    participant T as MCU testTask
+    C->>S: SYN
+    S->>C: SYN+ACK
+    C->>S: ACK（ESTABLISHED）
+    S->>T: 中断 / GlobInt → net_poll()
+    Note over T: net_accept() → phase_active
+    C->>S: [64B 数据]（recv_len = N）
+    S->>T: 中断 → net_poll()
+    Note over T: phase6_run()：net_recv(N) → 字节校验 → TEST_CHECK(累加和)
+    S->>C: [64B 回显]（net_send）
+    Note over C: 逐字节比对 + 累加和（重复 N 轮 / 多包）
+    C->>S: FIN/RST（DISCONNECT）
+    S->>T: 中断 → net_poll()
+    Note over T: net_recv EOF → auto_relisten
+    S->>S: 自动 OPEN + TCP_LISTEN
+    C->>S: SYN（新连接）
+    Note over C,S: LISTEN 自动恢复，重新接受
 ```

 - `phase6_run()` 为**纯回显**：非阻塞 `net_recv(sockfd, s_rx_buf, TEST_BUF_SIZE, NET_MSG_DONTWAIT)` 收到 N 字节后，`net_send(sockfd, s_rx_buf, N, 0)` 原样回显；不做固件侧字节自检（字节完整性由 PC 侧 `data == test_data` 校验）。
@@ -728,40 +717,32 @@ net_socket(NET_AF_INET, NET_SOCK_STREAM)      // 取空闲 Socket（非监听 So

 **架构图（组件）**：

-```
-┌──────────────┐                    TCP 8081                    ┌──────────────────────────┐
-│   PC (Python) │ ◀─────────────────────────────────────────── │  CH395F (192.168.1.100)  │
-│ tcp_server    │                  Ethernet                     │  Socket N（非 0 空闲）    │
-│ (回显服务器)   │              (SPI2, 分频=8)                   └────────────┬─────────────┘
-└──────────────┘                                                    SPI    │
-                                                                          ▼
-                                                            ┌──────────────────────────┐
-                                                            │      MCU (STM32F407)      │
-                                                            │ netTask: net_poll() 10ms  │
-                                                            │ testTask:                 │
-                                                            │  net_layer_client_test_main│
-                                                            │   └─ net_connect→收发→close│
-                                                            └──────────────────────────┘
+```mermaid
+flowchart LR
+    MCU["MCU（STM32F407）<br/>netTask: net_poll() 10ms<br/>testTask: net_layer_client_test_main()<br/>└─ net_connect → 收发 → close"] -->|"SPI2（分频=8）"| CH["CH395F（192.168.1.100）<br/>Socket N（非 0 空闲）"]
+    CH -->|"TCP 8081 · 以太网"| PC["PC（Python）<br/>tcp_server（回显服务器）"]
 ```

 **会话时序图（Client 主动连接）**：

-```
- PC (Server :8081)         CH395F Socket N                MCU testTask
-     │                          │                            │
-     │   (Python tcp_server)    │                            │ net_layer_client_test_main()
-     │                          │◀─ net_socket()+net_connect()│ (异步下发 CONNECT)
-     │◀────────────── SYN ──────│                            │
-     │────── SYN+ACK ─────────▶│  ESTABLISHED               │
-     │                          │── 中断/GlobInt ───────────▶│ net_poll()
-     │                          │                            │ net_select() 可写 → 建链
-     │◀────────────── [64B] ────│  net_send()                │
-     │  (回显服务器原样返回)      │                            │
-     │   [64B 回显] ───────────▶│  recv_len = N              │
-     │                          │── 中断 ───────────────────▶│ net_poll()
-     │                          │                            │ net_recv(N) → 字节校验
-     │                          │                            │ TEST_CHECK(累加和)
-     │                          │◀─ net_close() ─────────────│ 释放 Socket N
+```mermaid
+sequenceDiagram
+    participant C as PC（Server :8081）
+    participant S as CH395F Socket N
+    participant T as MCU testTask
+    Note over T: net_layer_client_test_main()
+    T->>S: net_socket() + net_connect()（异步下发 CONNECT）
+    S->>C: SYN
+    C->>S: SYN+ACK（ESTABLISHED）
+    S->>T: 中断 / GlobInt → net_poll()
+    Note over T: net_select() 可写 → 建链
+    T->>S: [64B]（net_send）
+    S->>C: [64B]
+    Note over C: 回显服务器原样返回
+    C->>S: [64B 回显]（recv_len = N）
+    S->>T: 中断 → net_poll()
+    Note over T: net_recv(N) → 字节校验 → TEST_CHECK(累加和)
+    T->>S: net_close()（释放 Socket N）
 ```

 - `net_layer_client_test_main()` 为**独立入口**：使用非 0 空闲 Socket 连接 PC，不在 `net_layer_test_main()` 的监听循环内；由 `StartCh395fTestTask` 的 NET 分支按宏调用。