HMC-RPC

HMC 异构内存通信生态

面向异构内存与多路径传输的 C++ RPC 运行时

HMC-RPC 构建在团队自主研发的 HMC（Heterogeneous Memory Communication）通信底座之上，为远程调用提供稳定线协议、方法分发、强类型编解码、请求生命周期以及 TCP、UDS 和 UCX 大消息数据面。HMC 统一抽象 CPU、GPU 与其他加速器内存，使 RPC 语义不必绑定单一设备或传输实现。

快速开始 · 架构 · 支持状态 · 性能与验证 · 文档 · Roadmap

HMC 异构通信底座

HMC（Heterogeneous Memory Communication）是团队自主研发的一个面向异构系统（CPU、GPU 和各类加速器）的通信框架。它提供：

统一的内存抽象：Memory 一个与设备无关的接口，用于申请、释放缓冲区，并在不同设备之间复制数据。
统一的注册 I/O 缓冲区：ConnBuffer 一个稳定、已注册的缓冲区，作为所有网络传输的数据暂存区（staging area）。
统一的传输抽象：Communicator 以同一套接口实现对端缓冲区之间的单边数据读写：
- ConnType.RDMA：依赖平台和设备能力。
- ConnType.UCX：常用于 CPU，以及部分 GPU-direct 配置。
用于同步与小消息的控制面（Control plane） 一个基于 rank 的控制信道，支持 TCP 和/或 UDS（同机）。

为什么选择 HMC-RPC

稳定的 RPC 语义：48 字节固定大端序头部，请求编号、方法编号、状态码和负载模式均显式编码，不依赖主机 ABI。
控制面与数据面分离：TCP 承载控制帧和通用回退路径，大负载可通过 HMC/UCX TAG 传输。
异构内存抽象：Memory、ConnBuffer 和 Communicator 隔离设备内存、注册缓冲区与具体传输路径。
可控并发与生命周期：持久连接、固定工作线程池、单连接多在途请求、乱序响应匹配、deadline、cancel 和优雅关闭。
可复现验证：提供单元测试、双进程集成测试、双机验证记录和 benchmark 矩阵脚本。
HMC 支持 CPU 内存以及多种加速器后端，包括：
- NVIDIA GPU（CUDA）
- AMD GPU（ROCm）
- 海光平台 / GPU（依赖具体平台；当你的构建产物中启用了对应后端时可用）
- 寒武纪 MLU（CNRT / Neuware）
- 摩尔线程 GPU（MUSA）

快速开始

环境要求

Linux
支持 C++14 的编译器
CMake 3.21 或更高版本
UCX；默认安装前缀为 /usr/local/ucx
rdma-core 开发库
GTest（仅在启用测试时需要）

没有检测到 GPU 工具链时，项目会构建 CPU-only 版本。UCX 安装在其他位置时，通过 UCX_ROOT 指定前缀，并确保运行时能够找到其共享库。

构建与测试

cmake -S . -B build-rpc \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTS=ON \
  -DUCX_ROOT=/usr/local/ucx

cmake --build build-rpc -j"$(nproc)"
ctest --test-dir build-rpc --output-on-failure

当前 CTest 包含统一单元测试、真实 TCP 双进程测试和 benchmark 烟雾测试。

运行第一个 RPC

终端 A 启动服务端：

./build-rpc/apps/rpc_tcp/hmc_rpc_tcp_server \
  --bind-address 127.0.0.1 \
  --port 18080 \
  --workers 4 \
  --max-connections 68 \
  --max-inflight 64

终端 B 调用 uppercase：

./build-rpc/apps/rpc_tcp/hmc_rpc_tcp_client \
  --server-address 127.0.0.1 \
  --port 18080 \
  --method uppercase \
  --message "hello hmc rpc" \
  --repeat 3

预期输出：

response[3]=HELLO HMC RPC
Completed 3 uppercase RPC call(s)

服务端内置三个演示方法：

方法	ID	行为
`echo`	1	原样返回字节负载
`uppercase`	2	将字符串转换为大写
`complex`	3	解码复合结构，处理后返回强类型结果

复合类型示例：

./build-rpc/apps/rpc_tcp/hmc_rpc_tcp_client \
  --server-address 127.0.0.1 \
  --port 18080 \
  --method complex \
  --message "typed payload" \
  --values "3,5,8"

序列化层逐字段编码字符串、动态数组和复合结构，不直接复制 C++ 对象内存，从而避免 padding、ABI 和主机端序差异。

架构

HMC-RPC 架构概览

HMC-RPC 将应用接口、调用生命周期、线协议和数据传输分层：

RpcCodec<T> 负责确定性大端序编解码。
Dispatcher 根据 method id 分发请求，运行时管理状态、截止时间与取消。
协议层通过 request id 匹配响应，并描述负载所在的数据路径。
TCP/UDS 提供可靠控制通道，HMC/UCX 承载大块数据。
HMC 向下统一 CPU、GPU 和其他加速器的内存与通信能力。

大消息路径

条件	协议模式	实际路径
负载不超过 4 KiB	`INLINE`	TCP 控制帧内联
负载大于 4 KiB，但未选择 UCX	`TCP_STREAM`	TCP 帧体
达到阈值且 UCX 准备成功	`HMC_BUFFER`	TCP 描述符 + UCX TAG

默认 UCX 阈值为 64 KiB。数据面在控制帧发出前准备失败时可以回退到 TCP；控制帧发出后的 UCX 失败不会自动重放，因为服务端可能已经执行过对应方法。

CPU UCX/TCP 双机基线的完整启动和 benchmark 命令见大消息数据面文档。

支持状态

RPC 与传输能力

能力	状态	说明
IPv4 TCP	已验证	loopback、双进程、双机、长连接和多客户端
Unix Domain Socket	已验证	同机进程间 RPC
TCP 单连接多在途	已验证	可配置 pipeline，支持乱序响应匹配
Deadline / Cancel	已验证	单次调用截止时间和显式取消
强类型编解码	已验证	字符串、动态数组和复合结构
CPU UCX TAG	已验证	预建长连接上的 1 MiB 请求/响应
CUDA device staging	已实现	具备代码路径和测试，缺少跨机 GDR 实测
RDMA / GDR	待硬件验证	不作为当前已完成能力
Future / Coroutine API	规划中	当前公开调用接口为同步模型

异构设备基础

平台	仓库中的实现	当前 RPC 验证范围
CPU	`HostMemory`、CPU `ConnBuffer`	TCP/UDS/UCX 已验证
NVIDIA CUDA	`CudaMemory`、构建探测、device staging	代码与测试路径
AMD ROCm	`RocmMemory`、ROCm IPC/P2P	后端源码
海光等 HIP/ROCm 兼容平台	复用具体环境中的 ROCm/HIP 能力	依赖 SDK，未独立验证
寒武纪 Neuware/CNRT	`NeuwareMemory`、构建探测、同机 P2P	后端源码
摩尔线程 MUSA	`MusaMemory`、构建探测	后端源码

“已实现”表示仓库中存在对应代码或测试路径，不等同于完成了特定硬件上的跨机正确性与性能验证。

性能与验证

以下结果用于说明当前版本的可复现基线，而不是硬件峰值。TCP 数据来自两台 Linux 节点、Release 构建、8 个服务端工作线程；每组执行 5 轮并取中位数。详细环境、方法和完整矩阵见 TCP 性能基线。

场景	结果
跨主机基础调用矩阵	410 / 410 通过
单条持久连接连续调用	200,000 次
4 客户端并发调用	400,000 次
64 B，8 客户端	35,490 RPC/s
4 KiB，8 客户端	20,511 RPC/s
单连接 pipeline 8 相对 pipeline 1	4.35–5.63 倍吞吐提升

单连接流水矩阵共完成 60 轮、1,200,000 次计时调用，每次均校验响应内容。完整结果见 TCP 多在途请求。

CPU UCX 大消息测试固定 UCX_TLS=tcp，在预建长连接上完成 1 MiB echo RPC：

场景	吞吐	p50
1 客户端，pipeline 1	21.787 RPC/s	49.030 ms
4 客户端，pipeline 4	54.653 RPC/s	295.839 ms

该结果验证 CPU UCX/TCP 的正确性和持续传输，不代表原生 RDMA 或 GDR 性能。

已知限制

UCX 短连接频繁创建、拆除和多进程并发重连时仍可能偶发传输错误；正式演示和性能测试使用预建、长生命周期数据端点。
服务端 UCX 大消息操作当前为保证正确性采用串行化；多连接可以并发提交，但单个大消息数据面尚未使用专用 progress 线程。
当前公开调用接口为同步 call()；多在途请求由多个调用线程与请求编号协作完成。
系统具备连接容量、pending 和每连接 inflight 边界，但尚无独立的全局请求队列背压策略。
GPU、P2P 和 GDR/RDMA 依赖具体设备、驱动、SDK 与网络拓扑，需要逐平台验证。

UCX 重连问题的证据和后续状态机约束见可靠性调查。

文档

项目结构

include/hmc/       RPC、协议、序列化与传输公开接口
src/rpc/           协议、运行时、TCP/UDS 和数据面实现
src/network/       UCX、RDMA、P2P 与连接管理
src/memories/      CPU 与加速器内存后端
apps/rpc_tcp/      服务端、客户端和 benchmark
tests/             单元、集成与双进程测试
scripts/           可复现 benchmark 脚本
docs/              设计、验证记录与性能报告