hs_dma_framework：面向高速数据采集的FPGA-Linux-ARM64一体化平台

hs_dma_framework：面向高速数据采集的 FPGA—Linux—ARM64 一体化平台

在高速数据采集系统中，数据产生、硬件传输、嵌入式处理、文件记录和现场操作往往分散在不同工程里。系统能否稳定运行，不只取决于某一个环节的峰值指标，也取决于这些环节能否形成清晰、连续、可验证的工作流。

hs_dma_framework 正是围绕这条工作流构建的一套 FPGA、Linux、ARM64 应用与上位机工具协同工程。它覆盖数据产生与校验、设备适配、记录与回放、文件管理、网络服务、客户端和图形界面，并提供从本机回归、RTL 仿真到目标板闭环的分层验证能力。

本文按照产品介绍的方式，从整体框架逐步介绍到几个代表性小模块，并给出平台验证中的测试输出、文件系统概览、GUI 截图和性能记录。为保持信息边界，文中不展开内部寄存器、设备地址、描述符字段、部署凭据和具体内存布局；性能数字也仅作为特定环境下的实测参考。

一句话定位

这是一套面向高速数据采集与数据链路验证的基础平台：让 FPGA 侧的数据能力能够被 ARM64应用持续承接，让记录、回放和校验可以闭环运行，也让上位机人员能够通过脚本或 GUI 观察和管理系统状态。

它的产品价值主要体现在五个方面：

产品能力	面向使用者的价值
完整数据链路	从数据产生到记录、回放、校验形成统一的操作流程
分层模块化	硬件适配、文件管理、业务应用和客户端可以分别演进
多种操作方式	同时提供 C 客户端、Python 客户端和 GUI，适配自动化与现场操作
可观察与可追踪	状态、文件、统计和日志有清晰的展示路径
分层验证体系	从快速 mock 回归到 RTL 仿真、软件集成和目标板闭环逐级验证

一、总体框架：四层协同，一条数据主线

从产品视角看，系统可以分成 FPGA 数据平面、Linux 设备适配、ARM64 应用平台和上位机工具四层。各层职责相对集中，既保留硬件链路的效率，也为上层提供相对稳定的使用方式。

图 1：产品级系统架构示意图。图中只保留对外理解所需的层次，不展开内部硬件接口细节。

层次	代表能力	产品侧作用
FPGA 数据平面	数据产生、传输、暂存与校验	为联调、回环和边界验证提供可控数据源
Linux 设备适配	设备访问、DMA 通道与中断协同	将硬件能力包装成用户态可以使用的入口
ARM64 应用平台	数据监测、记录、回放、统计和文件管理	承接连续运行的数据业务
上位机工具	C/Python 客户端与 GUI	支持脚本化管理、现场操作和问题观察
验证体系	mock、本机集成、RTL 仿真和目标板闭环	为功能完整性和性能表现提供分层证据

从数据流看，系统关注的是一条连续路径：

这条主线既可以服务于实际采集，也可以服务于数据通路回归。对于需要重复构造输入、保存结果并检查一致性的场景，统一链路能够减少各环节之间的手工拼接。

二、核心模块：从平台能力落到可复用组件

1. FPGA 数据产生与校验：为系统提供可控输入

平台内的 data_gen 能力用于产生可预测的数据，并在链路末端进行结果检查。它既可以独立完成数据联调，也可以与主应用的数据通路配合，适合用于以下工作：

• 在硬件联调前快速确认数据流和控制流程；
• 构造不同长度、不同通道和有限循环场景；
• 将“能收到数据”进一步提升为“数据内容经过检查”；
• 为记录、回放和存储链路提供稳定的对照输入。

这类模块的价值不在于替代真实采集源，而在于提供一套可重复的数据基准，使问题定位不必完全依赖现场偶发输入。

2. ARM64 应用平台：把硬件能力组织成业务流程

ARM64 应用层由硬件交互、文件管理、公共组件和网络服务等部分组成。对使用者而言，最重要的不是内部模块的划分，而是它能把多个动作组合成可理解的业务流程：

业务模块	主要职责	对外呈现
数据监测	接收硬件侧数据事件，组织待处理数据	数据状态、计数和日志
记录模块	将数据写入文件并维护进度	记录任务、文件大小和当前状态
回放/卸载模块	从文件读取数据并送回硬件链路	回放任务、速率和完成状态
文件管理模块	管理分类、文件和当前进度	查询、选择、刷新和持久化
统一服务	提供远程控制与查询能力	C/Python/GUI 共用的控制入口

这样的组合让系统可以从一次短数据回环扩展到连续记录、文件浏览、回放和统计查询，同时保持每个模块的职责边界。

3. 文件管理：让数据从“文件”变成可理解的对象

fm_system 负责把分类、文件和当前进度组织成统一的管理语义。上层不需要直接处理目录遍历和元数据细节，客户端可以围绕“分类—文件—当前状态”进行操作。

文件管理侧的产品体验包括：

• 分类和文件列表可以被 GUI、C 客户端和 Python 客户端以一致方式查询；
• 元数据持久化后可以重新加载，便于重启后的状态恢复；
• 记录进度和最终文件状态有明确的更新路径；
• 本机压力测试能够覆盖较大数量的目录、文件和并发清理操作。

4. SoftBus：连接生产与消费的缓冲模块

数据监测、记录和回放之间存在不同的工作节奏。工程使用共享的缓冲组件承接这些模块，将数据生产与数据消费解耦，并为槽位状态、占用和释放提供统一管理。

从产品角度看，它带来的好处是：短时速率波动不会立刻传递成接口抖动；记录与回放可以在各自的线程中推进；出现超时或停止时，资源能够沿统一生命周期完成回收。这里强调的是行为边界，而不是向使用者暴露内部并发实现。

5. 客户端与 GUI：把控制面做成可操作的工具

工程同时提供原生 C 客户端、纯标准库 Python 客户端和 Tkinter GUI。三者共享相同的管理语义，适合不同角色：

使用方式	适合场景	特点
C 客户端	自动化脚本、嵌入式联调、批量回归	轻量、直接、便于集成
Python 客户端	测试编排、快速验证和工具开发	便于组合操作和输出结果
GUI	现场查看、文件选择和任务管理	降低操作门槛，增强状态可见性

GUI 按连接/系统、查询、文件管理、记录/回放/统计以及数据产生/校验等主题组织页面。连接后会先识别服务端能力，再呈现可用操作；后台任务与界面更新分开处理，适合长时间操作和现场观察。

三、GUI 展示：让系统状态更容易被看见

下面的图片来自配套 mock 服务和真实 GUI 事件循环，展示的是控制面交互，不代表某一块 FPGA 或某一套存储设备的性能界面。

图 2：连接与系统页。可以看到连接结果、能力探测、状态查询和日志输出。没有挂接的能力会以不可用状态呈现，避免把能力缺失误判为操作失败。

图 3：文件管理页。分类、文件列表、当前选择和刷新动作被放在同一工作区中，便于现场人员快速确认数据对象。图中的 capture 为 mock 演示分类。

图 4：数据产生与校验页。输入项和控制按钮按任务组织，适合短回环、状态检查和问题复现。

当前 GUI 自测覆盖 5 个页面、44 个用户可见按钮，并包含初始化幂等、能力探测、文件浏览、空目录和刷新等场景。它的定位是现场管理和验证辅助工具，仍然保留 C/Python 接口作为更适合自动化的入口。

四、验证数据：让产品能力有可量化依据

平台采用分层验证方式。下面是当前验证快照，重点展示“哪些能力被覆盖”，而非将所有结果压缩成一个单一分数。

软件、客户端与 GUI

验证项	结果	覆盖重点
ARM64 应用、独立数据产生驱动、上位机客户端构建	3/3 成功	三类主要交付产物可以分别构建
data_gen mock smoke	7/7	参数、序列、多通道、状态、超时和销毁
软件边界测试	13/13	参数、错误路径、取消和清理
AVL 与文件管理测试	11/11；14/14	索引、文件/JSON 持久化和并发场景
Python 客户端 mock 回归	83/83	编解码、高层接口、文件操作和错误边界
GUI 页面与文件浏览器自测	15/15	页面、分类、选择、空目录和刷新
GUI 初始化与能力边界	4/4	初始化、重复初始化和能力缺失处理

RTL 与联合数据流

验证项	结果	说明
data_gen RTL 仿真	22/22	独立数据产生与校验场景
data_gen + hs_dma 联合仿真	10/10	联合数据流与边界场景
hs_dma 顶层 RTL 仿真	1/1；压力 8/8	RX/TX 数据流和多轮压力

代表性调试输出

下面保留了测试判定信息，省略设备地址、内部布局和部署细节：

$ make -C software/test/data_gen_driver_test smoke
[TEST] summary: 7/7 passed

$ ./boundary_test
[TEST] summary: passed=13 failed=0

$ python3 software/test/net_interface_gui/self_test.py
===== SUMMARY: 83 PASS / 0 FAIL =====

$ make SIM=icarus WAVES=0       # data_gen RTL
** TESTS=22 PASS=22 FAIL=0 SKIP=0 **

$ make SIM=icarus WAVES=0       # hs_dma 顶层 RTL
stress round 8/8 passed
ALL TESTS PASSED: TX 144 frames/335635 bytes, RX 176 frames/354864 bytes
** TESTS=1 PASS=1 FAIL=0 SKIP=0 **

这些输出体现了平台的一个基本设计取向：快速回归、软件边界、硬件仿真和真实链路分别回答不同问题。它们不能相互替代，但组合起来可以减少“只看一次联调结果”的不确定性。

五、文件系统概览：从元数据到实际样本

在文件管理集成测试中，系统会创建测试目录、配置文件和数据文件，验证保存、重读、文件状态更新及并发清理。下面给出文件系统层面的简要概览，数字属于测试产物规模，不代表部署环境必须采用相同目录或容量。

文件或产物	作用	当前观察
系统元数据 JSON	保存基础配置和分类关系	测试样例约 254 B，可重新读取
分类元数据 JSON	保存单个分类的文件目录	空分类样例约 38 B，保存/重读通过
记录数据文件	保存采集或回放样本	目标板闭环样本保留，并完成内容一致性检查
本机压力测试树	验证目录、文件和并发清理	约 2.46 万个文件、1.64 万个目录
交付静态库	支持 ARM64 应用、独立 data_gen 和上位机客户端	约 354 KiB、22 KiB、208 KiB

对实际产品使用而言，重要的是文件对象具备可查询的状态和进度，能够被不同客户端以相同语义访问；测试目录数量只是用来说明文件管理模块做过一定规模的本机压力验证。

六、性能记录：用闭环数据说明能力边界

已有目标板闭环记录显示了系统在真实设备、存储和 FPGA 数据链路上的表现。以下数据来自特定版本和特定测试环境，采用约数表达，不作为跨平台的固定承诺。

场景	记录结果	说明
多路文件闭环	记录阶段约 341 MB/s；回放侧约 1.6 GB/s	端到端 checker 零错误
保留式闭环样本	测试文件总计约 128 MiB	源文件与记录文件完成内容比对并保留
连续多轮回放	5 轮均通过；回放 I/O 约 347 MB/s	用重复运行观察链路稳定性
独立存储/P2P 探针	写入约 290–297 MB/s；读取约 375 MB/s	作为平台能力探针，不等同于完整业务吞吐

系统统计不仅关注 MB/s，也会同时核对传输字节数、块数、计时结果、最终文件和校验结果。这种记录方式更适合工程交付：当平台、位流、存储介质或系统负载发生变化时，可以重新获得一组有上下文的数字，而不是依赖单个峰值。

七、交付形态：适合从联调逐步走向现场使用

当前工程已经形成几类相互配合的交付产物：

产物	典型用途
ARM64 应用静态库	集成数据监测、记录、回放、文件管理和服务能力
独立数据产生驱动	单独进行数据产生/校验联调和硬件回归
上位机 C 客户端库	编写轻量自动化工具或集成到现有测试程序
Python 网络客户端	快速编排测试和制作辅助工具
Python GUI	现场查看状态、管理文件和执行常用操作
分层测试工程	为软件、RTL、联合链路和目标板验证提供入口

这种组合方式适合从“先在本机验证接口”开始，再逐步进入 RTL 仿真、目标板闭环和现场操作。不同阶段使用相同的模块语义，有助于减少从测试工具切换到产品工具时的重复工作。

八、适用场景与后续演进

适用场景

• FPGA 数据采集卡或数据产生 IP 的 Linux/ARM64 配套软件；
• 需要记录、回放和内容校验的嵌入式数据链路；
• 需要同时覆盖 C、Python 和 GUI 操作方式的联调项目；
• 需要把文件管理、数据统计和网络控制放在同一工程中的系统；
• 需要以 mock、仿真和目标板测试逐步建立交付信心的研发流程。

可以持续增强的方向

• 进一步固化 FPGA、驱动、应用和测试记录之间的版本配对；
• 将目标板短回归和性能趋势纳入更稳定的发布流程；
• 持续扩大 RTL 与软件边界覆盖，同时保持测试输出简洁可读；
• 为 GUI 增加更清晰的任务进度、历史记录和结果导出能力；
• 对长期运行和现场数据建立更完整的归档规范。

这些方向更多是产品化过程中的持续建设，而不是对当前框架能力的否定。平台已经具备较完整的骨架，后续重点是让版本、数据和验证结果更加容易被复用和追踪。

总结

hs_dma_framework 把 FPGA 数据通路、Linux 设备适配、ARM64 业务应用、文件管理、网络服务和上位机工具放进了同一个工程框架。它既可以作为数据采集系统的应用基础，也可以作为硬件链路回归与性能验证的平台。

从模块组织、GUI 体验、分层测试和已有闭环记录看，平台已经具备继续产品化演进的基础。更适合它的宣传方式不是承诺一个脱离环境的绝对数字，而是展示一条可运行、可观察、可校验的完整链路，以及在不同阶段都能留下证据的工程方法。