From 39117e90434559b294f7b98f505a271f3d620e4e Mon Sep 17 00:00:00 2001 From: Song-aff <281218023@qq.com> Date: Wed, 13 Sep 2023 22:07:04 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E6=94=B9=E9=83=A8=E5=88=86?= =?UTF-8?q?=E7=BB=86=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/tooling/debugging/openocd.md | 3 ++- src/tooling/debugging/probe-rs.md | 2 +- src/tooling/debugging/vscode.md | 20 +++++++++----------- src/tooling/espflash.md | 16 +++++++--------- src/tooling/simulating/index.md | 4 ++-- src/tooling/simulating/qemu.md | 12 +++++------- src/tooling/simulating/wokwi.md | 21 ++++++++++----------- src/tooling/visual-studio-code.md | 12 ++++++------ 8 files changed, 42 insertions(+), 48 deletions(-) diff --git a/src/tooling/debugging/openocd.md b/src/tooling/debugging/openocd.md index 2be72b9..039d77f 100644 --- a/src/tooling/debugging/openocd.md +++ b/src/tooling/debugging/openocd.md @@ -1,8 +1,9 @@ + # OpenOCD 与[`probe-rs`][probe-rs]类似，OpenOCD 不支持`Xtensa`架构。然而，Espressif 在[espressif/openocd-esp32][espressif-openocd-esp32]下维护了一个 OpenOCD 的分支，该分支支持 Espressif 的芯片。 -有关如何在您的平台上安装`openocd-esp32`的说明可以在[Espressif 文档][espressif-documentation]中找到。 +有关如何在你的平台上安装`openocd-esp32`的说明可以在[Espressif 文档][espressif-documentation]中找到。 [probe-rs]: ./probe-rs.md [espressif-openocd-esp32]: https://github.com/espressif/openocd-esp32 diff --git a/src/tooling/debugging/probe-rs.md b/src/tooling/debugging/probe-rs.md index 6e625a2..34c3479 100644 --- a/src/tooling/debugging/probe-rs.md +++ b/src/tooling/debugging/probe-rs.md @@ -35,7 +35,7 @@ ## 权限 - Linux -在 Linux 上，您可能会遇到与 Espressif 探针交互时的权限问题。安装以下`udev`规则并重新加载应该可以解决此问题。 +在 Linux 上，可能会遇到与 Espressif 探针交互时的权限问题。安装以下`udev`规则并重新加载应该可以解决此问题。 ```text # Espressif dev kit FTDI diff --git a/src/tooling/debugging/vscode.md b/src/tooling/debugging/vscode.md index b7bbcd8..188941b 100644 --- a/src/tooling/debugging/vscode.md +++ b/src/tooling/debugging/vscode.md @@ -1,6 +1,6 @@ # 在 Visual Studio Code 中进行调试 -还有一种可能性是直接在 Visual Studio Code 中进行图形输出进行调试。 +在 Visual Studio Code 中，还可以直接进行可视化的调试。 ## ESP32 @@ -35,7 +35,7 @@ // 更多信息请参见：https://github.com/Marus/cortex-debug/blob/master/package.json "name": "Attach", "type": "cortex-debug", - "request": "attach", // 附加而不是启动，因为否则会尝试写入flash，但会失败 + "request": "attach", // 使用 attach 而不是 launch，避免因为尝试写入 flash 导致运行失败 "cwd": "${workspaceRoot}", "executable": "target/xtensa-esp32-none-elf/debug/.....", "servertype": "openocd", @@ -64,7 +64,7 @@ 内置 JTAG 接口的可用性取决于 ESP32-C3 版本： - 早于 3 的版本**没有**内置 JTAG 接口。 -- 版本 3（及更高版本）**具有**内置 JTAG 接口，您无需连接外部设备即可进行调试。 +- 版本 3（及更高版本）**具有**内置 JTAG 接口，无需连接外部设备即可进行调试。 要查找 ESP32-C3 版本，请运行： @@ -82,19 +82,17 @@ espflash board-info | :-----------: | :-------: | | MTDO/GPIO7 | TDO | | MTDI/GPIO5 | TDI | +| MTCK/GPIO6 | TCK | +| MTMS/GPIO4 | TMS | +| 3V3 | VJTAG | +| GND | GND | -| MTCK/GPIO6 | TCK | -| MTMS/GPIO4 | TMS | -| 3V3 | VJTAG | -| GND | GND | - -> ⚠️ **注意**：在 Windows 上，`USB串行转换器A 0403 6010 00`驱动程序应为 WinUSB。 +> ⚠️ **注意**：在 Windows 上，`USB Serial Converter A 0403 6010 00`驱动程序应为 WinUSB。 2. 设置 VSCode 1. 安装 VS Code 的[Cortex-Debug][cortex-debug]扩展。 2. 在要调试的项目树中创建`.vscode/launch.json`文件。 3. 更新`executable`、`svdFile`、`serverpath`路径和`toolchainPrefix`字段。 - ```json { // 使用IntelliSense了解可能的属性。 @@ -106,7 +104,7 @@ espflash board-info // 更多信息请参见：https://github.com/Marus/cortex-debug/blob/master/package.json "name": "Attach", "type": "cortex-debug", - "request": "attach", // 附加而不是启动，因为否则会尝试写入flash，但会失败 + "request": "attach", // 使用 attach 而不是 launch，避免因为尝试写入 flash 导致运行失败 "cwd": "${workspaceRoot}", "executable": "target/riscv32imc-unknown-none-elf/debug/examples/usb_serial_jtag", // "servertype": "openocd", diff --git a/src/tooling/espflash.md b/src/tooling/espflash.md index fa3da5e..07bf232 100644 --- a/src/tooling/espflash.md +++ b/src/tooling/espflash.md @@ -1,6 +1,6 @@ # `espflash` -`espflash`是一个基于[esptool.py][esptool]的 Espressif SoCs 和模块的串行闪存工具。 +`espflash`是一个基于[esptool.py][esptool]的 Espressif SoC 和模块的串口下载工具。 [`espflash`][espflash]仓库包含两个 crate，`cargo-espflash`和`espflash`。有关这些 crate 的更多信息，请参见下面的各自部分。 @@ -11,7 +11,7 @@ ## `cargo-espflash` -为`cargo`提供一个子命令，处理交叉编译和闪存。 +为`cargo`提供一个子命令，处理交叉编译和下载。 要安装，请运行： @@ -19,7 +19,7 @@ cargo install cargo-espflash ``` -此命令必须在 Cargo 项目中运行，即包含`Cargo.toml`文件的目录。例如，要构建名为“blinky”的示例，将生成的二进制文件闪存到设备中，然后随后启动串行监视器： +此命令必须在 Cargo 项目中运行，即包含`Cargo.toml`文件的目录。例如，要构建名为“blinky”的示例，将生成的二进制文件下载到设备中，然后随后启动串行监视器： ```shell cargo espflash flash --example=blinky --monitor @@ -31,7 +31,7 @@ cargo espflash flash --example=blinky --monitor ## `espflash` -提供一个独立的命令行应用程序，将 ELF 文件闪存到设备中。 +提供一个独立的命令行应用程序，将 ELF 文件下载到设备中。 要安装，请运行： @@ -39,7 +39,7 @@ cargo espflash flash --example=blinky --monitor cargo install espflash ``` -假设您已经通过其他方式构建了 ELF 二进制文件，`espflash`可以用于将其下载到设备并监视串行端口。例如，如果您已经使用`idf.py`从[ESP-IDF][esp-idf]构建了名为“getting-started/blinky”的示例，您可以运行类似以下的命令： +假设你已经通过其他方式构建了 ELF 二进制文件，`espflash`可以用于将其下载到设备并监视串行端口。例如，如果你已经使用`idf.py`从[ESP-IDF][esp-idf]构建了名为“getting-started/blinky”的示例，可以运行类似以下的命令： ```shell espflash flash build/blinky --monitor @@ -47,14 +47,12 @@ espflash flash build/blinky --monitor 有关更多信息，请参见[`espflash` README][espflash-readme]。 -通过将以下内容添加到项目的`.cargo/config.toml`文件中，可以将`espflash`用作 Cargo 运行程序： - +`espflash`可以通过在你的项目的`.cargo/config.toml`文件中添加以下内容，作为 Cargo runner 来使用： ```toml [target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))'] runner = "espflash flash --monitor" ``` - -使用此配置，您可以使用`cargo run`下载和监视您的应用程序。 +使用此配置，可以通过`cargo run`下载和监控应用程序。 [esp-idf]: https://github.com/espressif/esp-idf [espflash-readme]: https://github.com/esp-rs/espflash/blob/master/espflash/README.md diff --git a/src/tooling/simulating/index.md b/src/tooling/simulating/index.md index 6fe727c..dccd7b8 100644 --- a/src/tooling/simulating/index.md +++ b/src/tooling/simulating/index.md @@ -1,8 +1,8 @@ # 仿真 -仿真项目可能很方便。它允许用户在没有可用硬件的情况下测试项目、尝试项目以及许多其他场景。 +仿真可能很方便。它允许用户使用 CI（持续集成）来测试项目、在没有可用硬件的情况下尝试项目，还有许多其他使用场景。 -目前，有几种方法可以在 Espressif 芯片上仿真 Rust 项目。每种方法都有一些限制，但它们正在迅速发展，并且每天都在变得更好。 +目前，有多种方法可以在 Espressif 芯片上仿真 Rust 项目。每种方法都有一些限制，但它们正在迅速发展，并且每天都在变得更好。 在本章中，我们将讨论当前可用的仿真工具。 diff --git a/src/tooling/simulating/qemu.md b/src/tooling/simulating/qemu.md index 8a7b27c..620286d 100644 --- a/src/tooling/simulating/qemu.md +++ b/src/tooling/simulating/qemu.md @@ -3,31 +3,29 @@ Espressif 维护了一个 QEMU 的分支，位于[espressif/QEMU][espressif-qemu]，其中包含了必要的补丁，使其能够在 Espressif 芯片上运行。 请参考[QEMU wiki][qemu-wiki]以了解如何构建 QEMU 并使用它来仿真项目。 -构建完成 QEMU 后，您应该有`qemu-system-xtensa`文件。 +构建完成 QEMU 后，应该有`qemu-system-xtensa`文件。 [espressif-qemu]: https://github.com/espressif/qemu [qemu-wiki]: https://github.com/espressif/qemu/wiki -## 使用 QEMU 运行您的项目 +## 使用 QEMU 运行项目 -> ⚠️ **注意**: 目前只支持 ESP32，因此请确保您正在编译`xtensa-esp32-espidf`目标。 +> ⚠️ **注意**: 目前只支持 ESP32，因此请确保正在编译`xtensa-esp32-espidf`目标。 -要在 QEMU 中运行我们的项目，我们需要一个固件/镜像，其中包含引导加载程序和分区表的合并。 +要在 QEMU 中运行我们的项目，我们需要一个固件（firmware）/镜像（image），其中包含引导加载程序（bootloader）和分区表的合并。 我们可以使用[`cargo-espflash`][cargo-espflash]来生成它： ```shell cargo espflash save-image --chip esp32 --merge --release ``` -如果您想使用[`espflash`][espflash]，您可以先构建项目，然后生成镜像来实现相同的结果： - +如果想使用[`espflash`][espflash]，可以先构建项目，然后生成镜像来实现相同的结果： ```shell cargo build --release espflash save-image --merge ESP32 target/xtensa-esp32-espidf/release/ ``` 现在，在 QEMU 中运行镜像： - ```shell /path/to/qemu-system-xtensa -nographic -machine esp32 -drive file=,if=mtd,format=raw ``` diff --git a/src/tooling/simulating/wokwi.md b/src/tooling/simulating/wokwi.md index 41b585e..14e7504 100644 --- a/src/tooling/simulating/wokwi.md +++ b/src/tooling/simulating/wokwi.md @@ -8,36 +8,35 @@ Wokwi 提供了 Wi-Fi 仿真、虚拟逻辑分析仪和[GDB 调试][gdb-debuggin [wokwi]: https://wokwi.com/ [wokwi-rust]: https://wokwi.com/rust -[gdb-debugging]: https://docs.wokwi.com/gdb-debugging -[wokwi-documentation]: https://docs.wokwi.com/ -[wokwi-simulation-features]: https://docs.wokwi.com/guides/esp32#simulation-features +[gdb-debugging]: https://docs.wokwi.com/zh-CN/gdb-debugging +[wokwi-documentation]: https://docs.wokwi.com/zh-CN/ +[wokwi-simulation-features]: https://docs.wokwi.com/zh-CN/guides/esp32#simulation-features ## 使用 Wokwi VS Code 扩展 - -Wokwi 提供了一个 VS Code 扩展，允许您通过添加几个文件直接在代码编辑器中模拟项目。 +Wokwi 提供了一个 VS Code 扩展，允许通过添加几个文件直接在代码编辑器中模拟项目。 更多信息，请参考[Wokwi 文档][wokwi-vscode]。 -您还可以使用 VS Code 调试器调试代码，请参考[调试您的代码][wokwi-debugging]。 +还可以使用 VS Code 调试器调试代码，请参考[调试你的代码][wokwi-debugging]。 当使用任何[模板][templates]并且不使用默认值时，会有一个提示(`Configure project to support Wokwi simulation with Wokwi VS Code extension?`)，生成所需的文件以使用 Wokwi VS Code 扩展。 ![Wokwi VS Code示例](../../assets/wokwi-vscode.png) -[wokwi-vscode]: https://docs.wokwi.com/vscode/getting-started -[wokwi-debugging]: https://docs.wokwi.com/vscode/debugging +[wokwi-vscode]: https://docs.wokwi.com/zh-CN/vscode/getting-started +[wokwi-debugging]: https://docs.wokwi.com/zh-CN/vscode/debugging [templates]: ./../../writing-your-own-application/generate-project/index.md ## 使用`wokwi-server` -[`wokwi-server`][wokwi-server]是一个 CLI 工具，用于启动您的项目的 Wokwi 仿真。也就是说，它允许您在本地或容器中构建项目，并模拟生成的二进制文件。 +[`wokwi-server`][wokwi-server]是一个 CLI 工具，用于启动项目的 Wokwi 仿真。也就是说，它允许在本地或容器中构建项目，并模拟生成的二进制文件。 -[`wokwi-server`][wokwi-server]还允许在其他 Wokwi 项目上模拟您的二进制文件，除了芯片本身外还有更多的硬件部件。请参考[`wokwi-server`][wokwi-server-custom] README 的相应部分以获取详细说明。 +[`wokwi-server`][wokwi-server]还允许在其他 Wokwi 项目上模拟二进制文件，除了芯片本身外还有更多的硬件部件。请参考[`wokwi-server README` 的相应部分][wokwi-server-custom] 以获取详细说明。 [wokwi-server]: https://github.com/MabezDev/wokwi-server [wokwi-server-custom]: https://github.com/MabezDev/wokwi-server#simulating-your-binary-on-a-custom-wokwi-project ## 自定义芯片 -Wokwi 允许生成自定义芯片，让您编程不受 Wokwi 支持的组件的行为。更多详情，请参考官方[Wokwi 文档][wokwi-custom-chip]。 +Wokwi 允许生成自定义芯片，让你对 Wokwi 不支持的组件的行为进行编程。更多详情，请参考官方[Wokwi 文档][wokwi-custom-chip]。 自定义芯片也可以用 Rust 编写！请参考[Wokwi Custom Chip API][rust-chip-api]以获取更多信息。例如，使用 Rust 编写的自定义[反相器芯片][custom-chip-example]。 diff --git a/src/tooling/visual-studio-code.md b/src/tooling/visual-studio-code.md index 9bc14df..b64cb41 100644 --- a/src/tooling/visual-studio-code.md +++ b/src/tooling/visual-studio-code.md @@ -2,9 +2,9 @@ Microsoft 的[Visual Studio Code][vscode]文本编辑器以及[Rust Analyzer][rust-analyzer]扩展，也称为 RA，是较常见的开发环境之一。 -Visual Studio Code 是一个开源的跨平台图形化文本编辑器，具有丰富的扩展生态系统。[Rust Analyzer 扩展][rust-analyzer-extension]为 Rust 提供了[语言服务器协议][language-server-protocol]的实现，并包括自动完成、跳转到定义等功能。 +Visual Studio Code 是一个开源的跨平台图形化文本编辑器，具有丰富的扩展生态系统。[Rust Analyzer 扩展][rust-analyzer-extension]为 Rust 提供了[Language Server Protocol（语言服务器协议][language-server-protocol]的实现，并包括自动完成、跳转到定义等功能。 -Visual Studio Code 可以通过最流行的软件包管理器安装，也可以在官方网站上获得安装程序。[Rust Analyzer 扩展][rust-analyzer-extension]可以通过内置的扩展管理器在 Visual Studio Code 中安装。 +Visual Studio Code 可以通过大多数流行的软件包管理器安装，也可以在官方网站上获得安装程序。[Rust Analyzer 扩展][rust-analyzer-extension]可以通过内置的扩展管理器在 Visual Studio Code 中安装。 除了 Rust Analyzer 之外，其他扩展也可能有所帮助： @@ -18,11 +18,11 @@ Visual Studio Code 可以通过最流行的软件包管理器安装，也可以 [even-better-toml]: https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml [crates]: https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates -## 技巧和诀窍 +## 实用建议 ### 在`no_std`下使用 Rust Analyzer -如果您正在为不支持`std`的目标开发，Rust Analyzer 可能会表现出奇怪的行为，通常会报告各种错误。这可以通过在项目中创建`.vscode/settings.json`文件并填充以下内容来解决： +如果为不支持`std`的目标开发，Rust Analyzer 可能会表现出奇怪的行为，通常会报告各种错误。这可以通过在项目中创建`.vscode/settings.json`文件并填充以下内容来解决： ```json { @@ -32,7 +32,7 @@ Visual Studio Code 可以通过最流行的软件包管理器安装，也可以 ### 在使用自定义工具链时使用 Cargo 提示 -如果您正在使用自定义工具链，就像在`Xtensa`目标中一样，您可以通过`rust-toolchain.toml`文件向`cargo`提供一些提示，以改善用户体验： +如果正在使用自定义工具链，就像在`Xtensa`目标中一样，可以通过`rust-toolchain.toml`文件向`cargo`提供一些提示，以改善用户体验： ```toml [toolchain] @@ -43,7 +43,7 @@ targets = ["xtensa-esp32-none-elf"] ## 其他 IDE -我们选择覆盖 VS Code，因为它对 Rust 有很好的支持，并且在开发人员中很受欢迎。还有其他可用的 IDE 具有相当的 Rust 支持，例如[CLion][clion]和[vim][vim]，但这些超出了本书的范围。 +选择介绍 VS Code 是因为它对 Rust 有很好的支持，并且在开发者中很受欢迎。还有其他一些 IDE 也有相当的 Rust 支持，如 CLion 和 vim，但这些不在本书的讨论范围内。 [clion]: https://www.jetbrains.com/clion/ [vim]: https://www.vim.org/