# GD32E230C CMake + GCC 构建说明

本项目已从 Keil MDK-ARM 迁移到 CMake + GCC 构建系统。

## 工具链要求

### 必需工具
1. **ARM GCC 工具链** - arm-none-eabi-gcc
   - 下载地址: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
   - 或使用包管理器安装 (Linux/macOS)

2. **CMake** (版本 3.15 或更高)
   - 下载地址: https://cmake.org/download/
   - Windows: 建议使用安装包并添加到 PATH
   - Linux: `sudo apt install cmake`
   - macOS: `brew install cmake`

3. **Make 工具**
   - Linux/macOS: 通常已预装
   - Windows:
     - 选项1: MinGW (`mingw32-make`)
     - 选项2: MSYS2/Cygwin
     - 选项3: Ninja (`ninja`)

## 项目结构

```
GD32E230C/
├── CMakeLists.txt                          # 主 CMake 配置文件
├── toolchain-arm-none-eabi.cmake           # ARM GCC 工具链定义
├── GD32E23x_Firmware_Library/
│   ├── CMSIS/
│   │   └── GD/GD32E23x/Source/GCC/
│   │       ├── startup_gd32e23x.s         # GCC 启动文件
│   │       └── gd32e23x_flash.ld          # 链接脚本
│   └── GD32E23x_standard_peripheral/       # 外设库
├── user/                                   # 用户代码
└── Utilities/                              # 工具库
```

## 构建方法

### 方法 1: 手动构建

#### Linux/macOS/Windows:
```bash
# 1. 创建构建目录
mkdir build
cd build

# 2. 配置项目
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-arm-none-eabi.cmake \
      -DCMAKE_BUILD_TYPE=Release \
      ..

# 3. 编译
make -j4              # Linux/macOS
mingw32-make -j4      # Windows (MinGW)
ninja                 # 或使用 Ninja
```

### 方法 2: 使用 CMake GUI (Windows)

1. 打开 CMake GUI
2. Source code: 选择项目根目录
3. Build directory: 选择 `build` 子目录
4. 点击 "Configure"
5. 在 "Specify toolchain file" 中选择 `toolchain-arm-none-eabi.cmake`
6. 点击 "Generate"
7. 点击 "Open Project" 或在命令行执行 `make`

## 输出文件

构建成功后，在 `build/` 目录下会生成:

- `GD32E230C_EVAL.elf` - 可执行文件 (包含调试信息)
- `GD32E230C_EVAL.hex` - Intel HEX 格式 (用于烧录)
- `GD32E230C_EVAL.bin` - 二进制格式 (用于烧录)
- `GD32E230C_EVAL.map` - 内存映射文件

## 烧录固件

使用以下工具烧录固件:

### 1. OpenOCD
```bash
openocd -f interface/stlink.cfg -f target/gd32e23x.cfg \
        -c "program build/GD32E230C_EVAL.elf verify reset exit"
```

### 2. ST-Link Utility (Windows)
- 打开 ST-Link Utility
- 连接目标板
- File → Open → 选择 `GD32E230C_EVAL.hex`
- Target → Program & Verify

### 3. PyOCD
```bash
pyocd flash -t gd32e230c8 build/GD32E230C_EVAL.hex
```

### 4. JLink
```bash
JLinkExe -device GD32E230C8 -if SWD -speed 4000 \
         -CommandFile flash.jlink
```

创建 `flash.jlink` 文件:
```
loadfile build/GD32E230C_EVAL.hex
r
g
exit
```

## 清理构建

```bash
rm -rf build          # Linux/macOS
rmdir /s /q build     # Windows
```

## 配置说明

### MCU 配置
在 `CMakeLists.txt` 中定义:
- **MCU型号**: GD32E230C8
- **CPU类型**: Cortex-M23
- **Flash**: 64KB (0x08000000)
- **RAM**: 8KB (0x20000000)

### 编译选项
- `-Os`: 优化代码大小
- `-g3`: 生成调试信息
- `-fdata-sections -ffunction-sections`: 分段存储
- `-Wl,--gc-sections`: 链接时移除未使用代码

### 修改 MCU 型号

如果使用不同的 GD32E23x 型号,需修改:

1. **CMakeLists.txt**:
   ```cmake
   set(MCU_MODEL GD32E230C8)  # 修改为你的型号
   ```

2. **gd32e23x_flash.ld**: 根据实际 Flash/RAM 大小修改
   ```ld
   MEMORY
   {
     FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 64K
     RAM (xrw)  : ORIGIN = 0x20000000, LENGTH = 8K
   }
   ```

## 调试

### 使用 GDB + OpenOCD
```bash
# 终端 1: 启动 OpenOCD
openocd -f interface/stlink.cfg -f target/gd32e23x.cfg

# 终端 2: 启动 GDB
arm-none-eabi-gdb build/GD32E230C_EVAL.elf
(gdb) target remote localhost:3333
(gdb) load
(gdb) monitor reset halt
(gdb) continue
```

### 使用 VSCode
安装扩展:
- Cortex-Debug
- C/C++

创建 `.vscode/launch.json`:
```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug (OpenOCD)",
      "type": "cortex-debug",
      "request": "launch",
      "servertype": "openocd",
      "cwd": "${workspaceRoot}",
      "executable": "${workspaceRoot}/build/GD32E230C_EVAL.elf",
      "configFiles": [
        "interface/stlink.cfg",
        "target/gd32e23x.cfg"
      ]
    }
  ]
}
```

## 常见问题

### 1. 找不到工具链
确保 ARM GCC 工具链在 PATH 中:
```bash
arm-none-eabi-gcc --version
```

### 2. 链接错误
检查链接脚本路径和内存配置是否正确。

### 3. 编译警告
某些 GD32 库文件可能产生警告,可以在 `CMakeLists.txt` 中添加:
```cmake
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-unused-parameter")
```

## 从 Keil 迁移的主要变化

1. **启动文件**: 从 ARM 格式转换为 GCC 格式
2. **链接脚本**: 从 `.sct` 转换为 `.ld` 格式
3. **编译器宏**: 保持 `GD32E230` 定义
4. **优化级别**: 使用 `-Os` (类似 Keil 的 Level 2)

## 参考资料

- [CMake 官方文档](https://cmake.org/documentation/)
- [ARM GCC 工具链文档](https://gcc.gnu.org/onlinedocs/)
- [GD32 官方网站](http://www.gd32mcu.com/)
- [OpenOCD 文档](http://openocd.org/doc/)

## 技术支持

如有问题,请检查:
1. 工具链版本是否正确
2. 路径中是否包含空格或特殊字符
3. CMake 版本是否满足要求
4. 链接脚本内存配置是否匹配芯片型号