Black Magic Probe 技术文档

本文档旨在帮助用户详细理解和正确使用 Black Magic Probe 项目。以下是项目的安装指南、使用说明以及项目 API 使用文档。

一、安装指南

1. 环境准备

在开始安装之前，请确保您的系统已安装以下工具：

• git
• meson (版本 0.61 或更高)
• ninja

根据您的需求，如果需要构建或工作在固件或 Black Magic Debug App (BMDA) 上，还需要以下工具：

Black Magic Debug 固件

• arm-none-eabi-gcc (来自 ARM，自建和发行版提供的版本目前无法使用)

如果您希望使用较旧的 gnu-rm ARM 工具链，这也是可以的，并且工作良好。

如果您从其他来源获得的工具链遇到问题，请首先检查是否是工具链的问题，如果是，请打开一个 issue，或更好，提交一个修复的 pull request。

Black Magic Debug App

• GCC 或 Clang (Clang 不是官方支持的)

如果希望为第三方探针启用支持，而不仅仅是官方原生硬件，还需要：

• libusb1
• libftdi1
• libhidapi

2. 构建固件

该项目使用 Meson 构建系统进行配置和构建。您需要创建一个构建目录，然后根据您的需求配置构建。

项目的构建选项如下：

• probe：固件将运行的硬件平台
• targets：启用的调试目标
• debug_output：启用调试输出（用于调试 BMD 堆栈，而非调试目标）
• rtt_support：启用 RTT（实时传输）支持

您可以在 meson configure 命令的输出中查看所有可用的项目选项和有效值。

以下命令是从您克隆的 blackmagic 仓库的根目录运行的：

cd /path/to/repository/blackmagic

构建固件

要构建固件，您需要配置探针硬件以及要使用的交叉编译工具链。

对于每个支持的硬件探针，都有一个交叉文件可用，为它提供了一套合理的默认配置。

对于原生探针的构建配置命令可能如下：

meson setup build --cross-file cross-file/native.ini

即使您使用预配置的交叉文件，您仍然可以通过 -Doption=value 在同一配置命令中覆盖其默认值，或者在 更改构建配置 中稍后进行。

或者（对于高级用户），如果您想手动配置，例如在编写新探针支持或不同工具链时，可以运行：

meson setup build --cross-file cross-file/arm-none-eabi.ini -Dprobe=native -Dtargets=cortexm,stm

现在您应该有一个 build 目录，从中可以构建固件，这也是您的二进制文件将出现的地方。

meson compile 命令将构建默认目标，如果您从 build 目录内运行命令，可以省略 -C build：

meson compile -C build

您现在应该在 build 目录中看到以下结果文件：

• blackmagic_native_firmware.bin
• blackmagic_native_firmware.elf

这些是您将用于刷新到探针的二进制文件。

region `rom' 溢出

在处理非默认配置或 Git 上最新版本的项目时，可能会出现固件无法适应配置探针的可用空间的情况，如下所示：

arm-none-eabi/bin/ld: region `rom' overflowed by 4088 bytes
Memory region         Used Size  Region Size  %age Used
             rom:      135160 B       128 KB    103.12%
             ram:        5708 B        20 KB     27.87%
collect2: error: ld returned 1 exit status

这不是意外的情况，因为一些硬件探针的固件空间有限。您可以禁用一些功能或目标支持来解决这个问题：

meson configure build -Dtargets=cortexm,stm -Drtt_support=false

3. 构建 Black Magic Debug App

Black Magic Debug App (BMDA) 默认总是与固件一起构建。只要找到所有依赖项，就可以在 build 目录下找到可执行文件，名为 blackmagic。

如果您只想构建 BMDA，可以将硬件 probe 选项设置为空字符串 -Dprobe=''，这是默认值：

meson setup build

现在您应该有一个 build 目录，从中可以构建应用程序，这也是您的可执行文件将出现的地方。

meson compile 命令将构建默认目标，如果您从 build 目录内运行命令，可以省略 -C build：

meson compile -C build

您现在应该在 build 目录中看到以下结果文件：

• blackmagic

二、项目使用说明

1. Black Magic Debug 固件使用

以下是使用 Black Magic Debug 固件的示例：

> arm-none-eabi-gdb gpio.elf
...<GDB 版权信息>
(gdb) tar ext /dev/ttyACM0
远程调试使用 /dev/ttyACM0
(gdb) mon s
目标电压：2.94V
可用目标：
No. Att Driver
 1      STM32F40x M3/M4
(gdb) att 1
连接到程序：/devel/en_apps/gpio/f4_discovery/gpio.elf，远程目标
0x08002298 在 UsartIOCtl ()
(gdb) load
加载段 .text，大小 0x5868 lma 0x8000000
加载段 .data，大小 0x9e0 lma 0x8005868
加载段 .rodata，大小 0x254 lma 0x8006248
起始地址 0x800007c，加载大小 25756
传输率：31 KB/秒，919 字节/写入。
(gdb) b main
在 0x80000e8 处设置断点：文件 /devel/en_apps/gpio/f4_discovery/../gpio.c，行 70。
(gdb) r
开始程序：/devel/en_apps/gpio/f4_discovery/gpio.elf
注意：自动使用硬件断点来读取只读地址。

2. Black Magic Debug App 使用

您还可以将 Black Magic Debug 套件构建为名为 Black Magic Debug App (BMDA) 的 PC 程序。

此程序构建的是在 Black Magic Probe 上运行的同一 GDB 服务器。与 Black Magic Probe GDB 服务器的连接通过串行线进行，而与 Black Magic Debug App 的连接通过 TCP 端口 2000 进行，对于更多实例，端口会更高。使用 "tar(get) ext(ended) :2000" 进行连接。

Black Magic Debug App 可以与以下设备通信：

• Black Magic Probe 固件探针通过 USB-串行端口
• ST-Link v2、v2.1 和 v3（带有最新固件）
• CMSIS-DAP 兼容探针
• J-Link 探针
• FTDI MPSSE based 探针

当只连接到单个 BMP 支持的探针时，无参数启动 blackmagic 会启动服务器。当连接多个 BMP 支持的探针时，显示它们类型、位置和序列号，然后程序退出。添加 -P (位置) 到下一个调用以选择一个。对于上面示例会话的设置：

在另一个终端：

> blackmagic
Black Magic Debug App v1.9.2
适用于 Black Magic Probe、ST-Link v2 和 v3、CMSIS-DAP、J-Link 和 FTDI (MPSSE)
使用 1d50:6018 8BB20A03 Black Magic Debug
 Black Magic Probe  v1.9.2
监听 TCP: 2000

在 GDB 终端：

(gdb) tar ext :2000
远程调试使用 :2000
(gdb) mon s
...

Black Magic Debug App 还提供了对二进制文件的刷写、读取和验证功能，默认从最低闪存地址开始。-t 参数显示有关连接目标的信息。使用 -h/--help 获取支持选项的列表。

操作系统特定说明

在 *BSD 和 macOS 上，您应该使用 /dev/cu.usbmodemXXX。有关尝试使用 /dev/tty.usbmodemXXX 设备节点存在一些未解决的问题，涉及它在内部如何操作。

三、项目 API 使用文档

由于项目涉及固件和应用程序，API 使用文档通常涉及如何通过 GDB 与固件通信，以及如何使用 Black Magic Debug App 的命令行选项。

具体的 API 使用方法和文档通常在项目官方文档或相关开发指南中提供，这里不详细展开。

请根据项目的具体使用场景和需求，参考官方文档和开发指南，了解和使用项目提供的 API。

---

本文档提供了 Black Magic Probe 项目的安装、使用和 API 使用的基本指南，帮助用户更好地理解和利用该项目进行嵌入式微处理器的应用开发和调试。