教程 › ZDMA 安装指南

ZDMA 安装指南

从开箱到通过速度测试——让 ZDMA 正常运行所需的全部步骤。第 4 节讲怎么让手上的软件用上 ZDMA；如果要把它接进自己的项目，接入方式、版本规则与代码示例见 LeechCore 集成指南。

1. 概览

盒内包含

雷电版

• 1 × ZDMA
• 1 × Thunderbolt 数据线（1.5 m）
• 1 × 螺丝——体积很小，可能在清关/物流检查中丢失；也可以用机箱或显卡的备用螺丝固定 ZDMA。

OCuLink 版

• 1 × ZDMA（已装 OCuLink 接口模块）
• 1 × PCIe x4 OCuLink 转接板（装在控制电脑上）
• 1 × OCuLink 连接线（1 m）
• 1 × 螺丝——同上。

OCuLink 版不附雷电线。

接口

ZDMA 有两种接口版本。两版板卡、固件和软件完全相同，只有挡板上的接口模块不同。OCuLink 版直连 PCIe，中间没有雷电控制器和协议转换，开销更低，读取频率通常更高。请按订单上的 Interface: Thunderbolt 或 Interface: OCuLink 确认自己是哪一版。

雷电版

• Thunderbolt 接口 1——仅传输数据（不供电），兼容性最佳。推荐使用。
• Thunderbolt 接口 2——功能完整，支持 60 W 供电，用料更好。如果控制电脑必须通过其唯一的 Thunderbolt 接口供电，请使用它。

OCuLink 版

• OCuLink 接口（SFF-8612，仅一个口，旁边有绿色链路灯）——接随附的 PCIe x4 转接板（装在控制电脑上），或直接接带原生 OCuLink 口的控制电脑（例如 Minisforum UM790 XTX）。控制电脑不需要雷电口。

两版通用

• JTAG——用于固件刷写。

接口模块可以更换，后续会单独出售。更换需要拆开卡体、会破坏保修标签，仅建议过保用户自行更换。

2. 安装

1. 断电。关闭主机和控制电脑并断开电源，防止损坏设备。
2. 安装 ZDMA。将设备对准 PCIe X4 或 PCIe X16 插槽左侧的缺口，垂直插入，然后用螺丝固定。
   务必固定牢靠。ZDMA 较重——如果不固定，使用中可能因振动松脱而损坏。

   

   

3. 连接数据线——按您的版本看对应部分。

   雷电版

   使用随附的 Thunderbolt 线：一端接 ZDMA 的 Thunderbolt 接口 2，另一端接控制电脑的 Thunderbolt 接口。

   

   说明（雷电版） ZDMA 固定好之后，可以在电脑开机状态下插拔线缆——但软件正在使用 ZDMA 时切勿拔线，否则控制电脑可能崩溃。ZDMA 仅通过 Thunderbolt 传输数据：普通 USB-C 接口或普通 USB 线无法使用——请使用 Thunderbolt III 或 IV 线缆。

   OCuLink 版

   1. 控制电脑关机并断电后，把随附的 PCIe x4 OCuLink 转接板装进一个空闲的 PCIe x4 插槽（x8 / x16 亦可），用螺丝固定。控制电脑自带原生 OCuLink 口的，跳过这一步。
   2. 接 1 米 OCuLink 线：一端接 ZDMA 的 OCuLink 口，另一端接转接板（或原生 OCuLink 口）。
   3. 先给装着 ZDMA 的那台电脑（目标电脑）开机，再开控制电脑。
   说明（OCuLink 版） OCuLink 直接走 PCIe，不支持热插拔。两条铁律，每次都要遵守：① 装卡、装转接板、接线时两台电脑都必须关机——任何一台开着都不要插拔；② 每次开机，先开装着 ZDMA 的那台电脑，再开控制电脑。开机后才接的线要到下一次重启才会被识别；软件正在使用 ZDMA 时拔线可能导致控制电脑崩溃。连接线保持 1 米以内。
4. 安装驱动（在控制电脑上）——两版相同。解压驱动后：右键开始菜单 → 设备管理器 → 右键其他设备 / Management Card → 更新驱动程序 → 浏览我的电脑以查找驱动程序 → 选择驱动文件夹 → 下一步 → 仍然安装此驱动程序软件。

   下载 ZDMA 驱动

3. 测试

这一步只是确认硬件装好了、能正常跑起来，跟您之后要用什么软件无关。

1. 先关掉安全软件。卸载控制电脑上的杀毒软件，并关闭 Windows Defender。杀毒软件会拦截 DMA 读写，不关的话测试一定不通过。

   Defender Control 工具

2. 运行测试程序。下载并解压我们提供的测试文件，双击运行 DMAtest.exe。窗口里出现不停跳动的数字就说明通过了——数字越大越好，不用记具体数值，能持续刷新即可。我们的测试程序已经把需要的文件全部打包好（含最新版 leechcore.dll），解压即用，不用自己凑 DLL 版本。

   下载测试文件

   

   用我们提供的测试程序，可以跳过这一段。如果您用的是别人给的、或者自己编译的测试工具，请先把工具文件夹里的 leechcore.dll 换成我们提供的最新版本（点下面的按钮下载）。旧版本的 DLL 认不出 ZDMA，测试会一直不出数字，看起来就像硬件坏了一样。

   下载最新 leechcore.dll

   技术细节压缩包里的 leechcore.dll 与 leechcore_driver.dll 必须成对使用、来自同一 release，不要新旧混用。自建工具在跑业务代码前，建议先用 pcileech.exe -device fpga probe 确认版本对齐与设备连通性。

   如果一直不出数字，请先按《排障：设备识别不到》走一遍，那里涵盖接口、指示灯、固件、BIOS 和驱动。若仍未解决，请把完整的测试窗口截图发给我们（Discord 或邮件都可以），我们帮您看是哪一步的问题。

4. 如何使用

测试通过之后，剩下的都在软件一侧。ZDMA 在用户态就是 LeechCore 的那对 DLL：进程按 Windows 的 DLL 搜索顺序加载到我们提供的 leechcore.dll 与 leechcore_driver.dll，就能拿到设备。多数程序还带着自己那份旧版 LeechCore，所以先看它的 DLL 能不能替换。

情况一：DLL 可以替换（多数现成程序）

1. 退出目标程序，确认进程已经结束——后台驻留的实例也要退，否则 DLL 处于占用状态，改不动。
2. 解压我们提供的压缩包，得到 leechcore.dll 与 leechcore_driver.dll。
3. 把这两个文件覆盖进程序 exe 所在的目录，原文件留一份 .bak 以便回退。Windows 加载 DLL 时先搜 exe 所在目录，放这里就会优先命中。
   两个文件要一起换只换一个会版本错配：LcCreate 直接返回失败，表现就是「设备识别不到」。目录里若还有 vmm.dll（MemProcFS），同样必须取自同一 release。
4. 重新启动程序。

下载 leechcore.dll（含 driver）

情况二：DLL 换不了，或者换了不生效

出现下面任一情况，说明问题不在「替换文件」这一层：

• 程序目录里没有 leechcore.dll——DLL 被打包进 exe，运行时才释放，或者干脆走内存加载。
• 替换后程序起不来、报文件校验失败或直接闪退（程序自带完整性校验）。
• 替换后仍然报找不到 DMA 设备，而我们的测试程序能正常读出数字——硬件没问题，问题在调用方。

接下来看这个程序您改不改得动：

• 改得动——自己写的，或者是能自行编译的开源项目：按集成指南接一遍就行。DLL 与 exe 同目录、把两个 DLL 作为资源嵌入单文件 exe，两条路线都有完整代码示例和排错表。
• 改不动——闭源的第三方程序：把集成指南转给作者，说明您用的是 ZDMA。适配量不大，通常一轮就能搞定。

ZDMA / LeechCore 集成指南

5. 固件构建与刷写

用 LightningZ Flasher Tool 刷写，无需 Vivado。专门指南有分步说明：

ZDMA 固件刷写指南

ZDMA 的全部固件资料发布于 Ulf Frisk 的 pcileech-fpga / ZDMA 项目，包含完整的构建与刷写教程。