gd32c1x3-hal

HAL for the GD32C1x3 family of microcontrollers

快速入门指南

嵌入式Rust开发比普通开发需要更多的设置。

您还需要一个调试器，例如用于编程和调试的 ST-Link V3 mini。（市面上有很多不同的STLink调试器，所有这些调试器 都应该 能够按照这里提供的说明正常工作，其他JTAG或SWD调试器也可以使用，但可能需要不同的软件或配置）。

安装软件

要编程您的微控制器，您需要安装

• openocd 或 stlink
• gdb-multiarch（在某些平台上，您可能需要使用 gdb-arm-none-eabi 代替，确保更新 .cargo/config 以反映此更改）

最后，您需要为Rust编译器安装arm目标支持。为此，运行

rustup target install thumbv7em-none-eabihf

设置您的项目

像往常一样使用 cargo init 创建一个新的Rust项目。嵌入式开发的入门通常是闪烁LED，相应的代码在 examples/blinky.rs 中提供。将此文件复制到您的项目的 main.rs。

您还需要将一些依赖项添加到您的 Cargo.toml

[dependencies]
embedded-hal = "1.0.0"
nb = "1.1.0"
cortex-m = { version = "0.7.7", features = ["critical-section-single-core"] }
cortex-m-rt = "0.7.3"
# Panic behaviour, see https://crates.io/keywords/panic-impl for alternatives
panic-halt = "0.2.0"
gd32c1x3-hal = { version = "0.1.0", features = ["rt", "gd32c103"] }

如果您现在构建项目，您应该会得到一个错误：error: required language item, but not found: eh_personality。这个没有帮助的错误信息可以通过为正确的目标编译来解决。

我们还需要告诉Rust如何链接我们的可执行文件，以及如何在内存中布局结果。为了完成所有这些，请从gd32c1x3-hal仓库复制.cargo/config和memory.x到你的项目中。

cargo build

如果一切顺利，你的项目应该可以无错误地构建。

编程微控制器

现在，是时候在实际硬件上运行代码了。要做到这一点，请将调试探针连接到你的板，并使用以下命令启动openocd：

openocd -f interface/stlink-v3.cfg -f target/stm32f1x.cfg

如果你不使用stlink V3，请相应地更改接口。更多信息，请参阅embeddonomicon。

如果一切顺利，它应该检测到你的微控制器并显示Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints。请将其保持在后台运行。

我们将使用gdb将编译的二进制文件上传到微控制器并进行调试。由于你之前添加的.cargo/config，Cargo将自动启动gdb。还需要将gdb连接到openocd，这可以通过将.gdbinit复制到项目的根目录来实现。

你还需要告诉gdb从工作目录加载.gdbinit是安全的。

• Linux

  echo "set auto-load safe-path $(pwd)" >> ~/.gdbinit
  

• Windows

  echo set auto-load safe-path %CD% >> %USERPROFILE%\.gdbinit
  

如果一切顺利，cargo应该编译你的项目，启动GDB，加载你的程序并给你一个提示。如果你在GDB提示符中键入continue，你的程序应该启动，并连接到PC13的LED应该开始闪烁。

进一步探索

从现在起，你可以开始向你的项目添加更多代码，使其执行更有趣的操作。有关crate文档，请参阅docs.rs/gd32c1x3-hal。还有许多示例可用。如果文档或示例中有什么不清楚的地方，请提出问题，我们将努力改进。

选择微控制器

此crate支持gd32c1x3系列中的多个微控制器。你需要指定一个功能来指定要为哪个特定微控制器构建，例如gd32c103。

如果没有指定微控制器，crate将无法编译。

支持的微控制器

• gd32c103xx（例如GD32C103TB，GD32C103CB，GD32C103RB，GD32C103VB）
• gd32c113xx（例如GD32C113TB，GD32C113CB，GD32C113RB，GD32C113VB）

尝试示例

你可能需要给予cargo权限从工作目录调用gdb。

• Linux

  echo "set auto-load safe-path $(pwd)" >> ~/.gdbinit
  

• Windows

  echo set auto-load safe-path %CD% >> %USERPROFILE%\.gdbinit
  

编译，加载并启动硬件调试器。

$ rustup target add thumbv7em-none-eabihf

# on another terminal
$ openocd -f interface/$INTERFACE.cfg -f target/stm32f1x.cfg

# flash and debug the "Hello, world" example. Change gd32c103 to match your hardware
$ cargo run --features gd32c103 --example hello

$INTERFACE应根据你的调试硬件设置。如果你使用的是stlink V2，请使用stlink-v2.cfg。更多信息，请参阅embeddonomicon。

作为依赖项使用

当将此crate作为项目依赖项使用时，可以将微控制器指定为Cargo.toml定义的一部分。

gd32c1x3-hal = { version = "0.1.0", features = ["gd32c103", "rt"] }

文档

文档可以在docs.rs找到。

许可证

根据以下任一许可证授权：

• Apache License, Version 2.0 (LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT或http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确声明，否则您根据Apache-2.0许可证定义提交给作品包括在内的任何贡献，将根据上述方式双授权，不附加任何额外条款或条件。

有关更多详细信息，请参阅贡献指南。