build: 对齐模板工具链与 .vscode，APP 迁移 Bootloader 布局(0x08002000/54K)

工程编译与开发环境（参照 gd32e23x_template_cmake_vscode 模板） - cmake/arm-none-eabi-gcc.cmake：硬编码工具链路径改为 GD32_GCC_BIN 环境变量 / -DTOOLCHAIN_DIRECTORY 参数，与模板逐字一致 - .vscode：launch/tasks/settings/extensions 对齐模板，烧录与调试全部读取 GD32_GCC_BIN / GD32_OPENOCD_BIN / GD32_OPENOCD_SCRIPTS 环境变量；新增 J-Link 调试配置与 flash/reset/erase.jlink 脚本 - CMakeLists.txt：POST_BUILD 增加 Application/Application.hex 生成（J-Link 烧录脚本 loadfile 依赖） - 验证：Debug / Release 编译通过（本机 ARM GCC 15.2.1） Bootloader 布局适配（与旧版独立镜像不兼容，升级需整片烧录一次） - LD/gd32e23x_flash.ld：FLASH ORIGIN=0x08002000, LENGTH=54K - Src/system_gd32e23x.c：VECT_TAB_OFFSET=0x2000——Bootloader 不写 VTOR，APP 必须自设向量表，否则中断落回 Bootloader 向量表 - 验证：.vectors 链接于 0x08002000，固件 12164B（54KB 上限 22%）驱动修复 - Src/ldc1612.c：ldc1612_config_single_channel 各步骤 I2C 写入检查返回值，失败立即返回错误（原审查项 L3）文档 - README：重写本地编译/烧录/调试说明，新增"固件布局与 Bootloader"章节
2026-09-26 18:41:29 +08:00
parent 59f6e917fd
commit 89e7191cd5
13 changed files with 446 additions and 217 deletions
@@ -1,11 +1,36 @@
-# GD32E23x 工程模板
+# LDC1612 传感器固件

-本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。
+本仓库基于 GD32E23x CMake + VSCode 工程模板（`gd32e23x_template_cmake_vscode`），包含 LDC1612 电感采样、TMP112 温度采集及补偿、RS485 命令处理。当前版本为 V1.0.1。固件采用 Bootloader + APP 布局：APP 链接在 `0x08002000`（54KB Flash / 8KB RAM），启动时自设向量表偏移；开发进度与审查资料见 `doc/` 目录。
+
+## 本地编译
+
+需要 CMake 3.20 或更新版本、Ninja 和 ARM GCC。CMake、Ninja 应在 `PATH` 中；ARM GCC 通过 `GD32_GCC_BIN` 指定，也可在配置时传入 `-DTOOLCHAIN_DIRECTORY="D:/toolchain/arm-gcc/bin"`，该参数优先于环境变量。工具链路径支持包根目录或 `bin` 目录。
+
+在工程根目录运行 PowerShell（工具链路径请替换为本机安装位置）：
+
+```powershell
+$env:GD32_GCC_BIN = 'D:\toolchain\xpack-arm-none-eabi-gcc-15.2.1-1.1\bin'
+cmake --preset Debug
+cmake --build --preset Debug
+cmake --preset Release
+cmake --build --preset Release
+```
+
+输出位于 `Build/Debug` 或 `Build/Release`：`Application/Application.elf` 用于调试，`LDC1612_V1.0.1_APP_<日期>.bin` / `.hex` 为应用固件；`Application/Application.hex` 供 J-Link 烧录任务使用。应用固件不含 Bootloader：单独烧录需写到 `0x08002000`；整片烧录（Bootloader + APP + 标志页）用配套的固件合并工具（`gd32e230f8_firmware_merge_tool` 仓库）处理。详见[固件布局与 Bootloader](#固件布局与-bootloader)。
+
+如果切换 ARM GCC 版本，请使用新的构建目录，或通过 CMake Tools 的 “Delete Cache and Reconfigure” 重新配置。需要独立验证目录时可运行：
+
+```powershell
+cmake --preset Debug -B Build/local-check/Debug
+cmake --build Build/local-check/Debug
+```

 ---

 ## 目录

+- [本地编译](#本地编译)
+- [固件布局与 Bootloader](#固件布局与-bootloader)
 - [适用范围](#适用范围)
 - [默认配置](#默认配置)
 - [工具链准备](#工具链准备)
@@ -16,6 +41,26 @@

 ---

+## 固件布局与 Bootloader
+
+GD32E230F8（64KB Flash）按 Bootloader + APP 方式分区：
+
+| 区域 | 地址范围 | 说明 |
+|---|---|---|
+| Bootloader | `0x08000000` - `0x08001FFF`（8KB） | 随板提供，独立固件（`gd32e230f8_bootloader_hulk.bin`），负责 RS485 Ymodem OTA 与跳转 |
+| APP（本仓库） | `0x08002000` - `0x0800F7FF`（54KB） | 链接区 `FLASH ORIGIN=0x08002000, LENGTH=54K` |
+| 温度标定页（预留） | `0x0800F800` - `0x0800FBFF` | 预留存放标定数据；当前 APP 不访问，仅靠 54KB 链接上限保证不越界覆盖 |
+| 有效标志 | `0x0800FFFC` | Bootloader OTA 完成后自写 `0x0000EEEE`，跳转前校验 |
+
+工程侧的两个适配点（缺一不可）：
+
+- `LD/gd32e23x_flash.ld`：FLASH `ORIGIN = 0x08002000, LENGTH = 54K`；
+- `Src/system_gd32e23x.c`：`VECT_TAB_OFFSET = 0x2000`——Bootloader 不写 VTOR，APP 必须自己把向量表指到 `0x08002000`，否则中断会落回 Bootloader 向量表（现象：收到第一个 RS485 字节即死机）。
+
+⚠️ 与旧版布局（APP 链接在 `0x08000000` 的独立镜像）不兼容：从旧版升级需整片烧录一次。RS485 协议、命令集（M1-M6/M999/M9999）与回包格式无任何变化。布局依据与 Bootloader 反汇编分析见 `doc/LDC1612_工程审查与实验方案_2026-09-26.md`。
+
+---
+
 ## 适用范围

 - 适用于兆易创新 GD32E23x 系列 Cortex-M23 内核单片机
@@ -34,37 +79,49 @@

 ### 1. xPack GNU Arm Embedded GCC Toolchain

- **版本**：xpack-arm-none-eabi-gcc-11.3.1-1.1  
- **建议解压路径**：Tools/xpack-arm-none-eabi-gcc-11.3.1-1.1  
+- **原模板版本**：xpack-arm-none-eabi-gcc-11.3.1-1.1；本机编译验证使用 15.2.1-1.1。
+- **安装位置**：由本机统一管理，不提交到仓库。
 - **官方下载地址**：https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases  
 - **路径自定义说明**：  
-  如需自定义工具链路径，请同步修改以下文件：  
-  - `Projects/<BoardName>/<ProjectName>/cmake/arm-none-eabi-gcc.cmake`（第2行）  
-  - `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第12行）
+  编译器与 GDB 均通过 `GD32_GCC_BIN` 环境变量定位（或配置时传 `-DTOOLCHAIN_DIRECTORY`），CMake 文件与 `.vscode` 均无需修改路径。

-### 2. OpenOCD
+### 2. OpenOCD（GD-Link 支持）

 - **版本**：xpack-openocd-0.11.0-3  
- **建议解压路径**：Tools/xpack-openocd-0.11.0-3  
 - **获取地址**：https://github.com/burakenez/gd32-tools-xpack-openocd/tree/v0.11.0-3  
 - **说明**：  
  - 本版本提取自 Embedded Builder V1.4.1.23782。  
  - ⚠️ 请勿随意更换版本，因 GD32 MCU 支持有限，推荐严格使用此版本。  
 - **路径自定义说明**：  
-  如需自定义 OpenOCD 路径，请同步修改以下文件：  
-  - `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第14、17行）  
-  - `Projects/<BoardName>/<ProjectName>/.vscode/task.json` 中所有相关路径
+  通过两个环境变量定位，安装位置任意：  
+  - `GD32_OPENOCD_BIN`：`openocd.exe` 所在 `bin` 目录；  
+  - `GD32_OPENOCD_SCRIPTS`：OpenOCD `scripts` 目录。  
+  `.vscode` 的调试配置与烧录任务全部读取这两个变量，无需修改任何文件。

 ---

 ## 使用说明

-1. **准备工具链**  
-   - 按上述说明下载并解压 ARM GCC 和 OpenOCD 到 Tools 目录。
-   - Toolchain 目录内容不会被 git 跟踪，需自行维护。
+1. **配置环境变量**（用户级，按本机安装位置设置一次即可）

-2. **烧录固件**  
-   - 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。
+   | 环境变量 | 指向 | 用途 |
+   |---|---|---|
+   | `GD32_GCC_BIN` | ARM GCC 的 `bin` 目录 | 编译、GDB 调试 |
+   | `GD32_OPENOCD_BIN` | OpenOCD 的 `bin` 目录 | 烧录、调试 |
+   | `GD32_OPENOCD_SCRIPTS` | OpenOCD 的 `scripts` 目录 | 烧录、调试 |
+
+   设置后重开终端 / VSCode 生效。`cmd` 示例：`setx GD32_GCC_BIN "D:\toolchain\xpack-arm-none-eabi-gcc-15.2.1-1.1\bin"`。
+
+2. **编译**  
+   命令行见上文[本地编译](#本地编译)，或直接用 VSCode 的 CMake Tools 选择 Debug / Release preset 构建。
+
+3. **烧录固件**  
+   - **OpenOCD（GD-Link）**：VSCode 任务 `Flash MCU`（连带编译用 `Build and Flash`）；另有 `Reset MCU`、`Mass Erase MCU`、`OpenOCD Server` 任务。  
+   - **J-Link**：任务 `Flash MCU (Jlink)` 等，依赖构建生成的 `Build/<preset>/Application/Application.hex`。  
+   - 器件与接口在 `.vscode/settings.json` 的 `gd32.jlink.*` / `gd32.openocd.*` 中配置，当前为 GD32E230F8 / SWD。
+
+4. **调试**  
+   VSCode 调试配置有两个：`Debug with OpenOCD` 与 `Debug with J-Link`（均使用 cortex-debug，SVD 文件 `GD32E230.svd`，支持外设寄存器查看）。烧录调试器以 GD-Link 为例；J-Link 直接选用对应配置即可。

 ---

@@ -129,7 +186,6 @@

 - **快速上手示例**：如 main.c 的最小点灯/串口输出代码片段。
 - **常见问题与解答**：如构建失败、烧录失败的排查建议。
- **调试说明**：如何用 VSCode 调试、断点、查看寄存器等。
 - **多板卡适配说明**：如有多种硬件，如何切换 BoardName。
 - **贡献指南**：如何提交 PR、代码风格约定等。
 - **License 说明**：开源协议和版权声明。