---

统一通信X

统一通信X（UCX）是一个屡获殊荣的、经过优化且在生产环境中得到验证的通信框架，专为现代高带宽、低延迟网络而设计。它曾荣获RD-100奖。

UCX提供了一组抽象的通信原语，能够充分利用现有的硬件资源和卸载技术，包括RDMA（InfiniBand和RoCE）、TCP、GPU、共享内存以及网络原子操作等。

更多详细信息，请访问我们的文档网站。

请查阅我们的"成员自愿共识标准"和["符合出口管制的贡献提交"]政策(https://ucfconsortium.org/policy/)。

---

• 使用UCX
• 已知问题
• 架构
• 支持的传输协议
• 支持的CPU架构
• 许可证
• 我们的社区
• 贡献者协议与指南
• 出版物

---

使用UCX

发布版构建

通常，构建UCX需要先运行“configure”脚本，再执行“make”。如果使用的是发布版tarball，可在树形结构的根目录下执行以下命令来安装UCX系统：

$ ./contrib/configure-release --prefix=/where/to/install
$ make -j8
$ make install

如果是直接从Git仓库克隆，则应使用：

$ ./autogen.sh
$ ./contrib/configure-release --prefix=/where/to/install
$ make -j8
$ make install

注意：编译支持多种网络或其他特定硬件时，可能需要在运行configure时添加额外的命令行参数。

开发版构建

$ ./autogen.sh
$ ./contrib/configure-devel --prefix=$PWD/install-debug

*** 注意：由于包含额外的调试代码，UCX的开发版在运行时通常会带来较大的性能损失。

构建RPM包

$ contrib/buildrpm.sh -s -b

构建DEB包

$ dpkg-buildpackage -us -uc

构建Doxygen文档

$ make docs

使用UCX安装OpenMPI和OpenSHMEM

维基页面

使用UCX安装MPICH

维基页面

UCX性能测试

启动服务器：

$ ./src/tools/perf/ucx_perftest -c 0

连接客户端：

$ ./src/tools/perf/ucx_perftest <server-hostname> -t tag_lat -c 1

注意 -c 标志用于设置CPU亲和性。如果在同一台主机上同时运行这两个命令，请确保将亲和性分别设置到不同的CPU核心上。

运行内部单元测试

$ make -C test/gtest test

---

已知问题

• UCX 1.8.0版本存在一个可能导致数据损坏的bug，当TCP传输与共享内存传输结合使用时会出现此问题。建议升级到UCX 1.9.0或更高版本。1.8.0之前的版本不存在此问题。

• 由于pthread_rwlock函数中的已知缺陷，UCX在glibc 2.25至2.29版本中可能会挂起。当发生此类挂起时，其中一个UCX线程会卡在pthread_rwlock_rdlock（由ucs_rcache_get调用）中，即使没有其他线程持有锁。相关问题已在glibc Bug 23844中报告。如果遇到此问题，建议使用操作系统自带的glibc版本，或从源码编译低于2.25或高于2.29的glibc版本。

• 由于兼容性问题，当UCX与rdma-core v22一起使用时，设置UCX_DC_MLX5_RX_INLINE=0是不被支持的，并会导致DC传输不可用。此问题已在rdma-core v24中修复，并后向移植到了rdma-core-22.4-2.el7 rpm中。更多信息请参见ucx issue 5749。

• 如果网络路由识别错误，导致对等节点显示为“不可达”，可以通过设置UCX_IB_ROCE_REACHABILITY_MODE=all来更改默认的可达性检查模式。

---

架构

组件	职责	描述
UCP	协议层	实现高级抽象，如标签匹配、流、连接协商与建立、多路径传输以及不同内存类型的处理
UCT	传输层	实现低层通信原语，如主动消息、远程内存访问和原子操作
UCS	服务层	提供常用的数据结构、算法和系统工具
UCM	内存管理层	拦截内存分配和释放事件，用于内存注册缓存

---

支持的传输协议

• Infiniband
• Omni-Path
• RoCE
• Cray Gemini和Aries
• CUDA
• ROCm
• 共享内存
  • posix、sysv、cma、knem和xpmem
• TCP/IP

注： UCX >= 1.12.0要求rdma-core >= 28.0或MLNX_OFED >= 5.0才能支持Infiniband和RoCE传输。

---

支持的CPU架构

• x86_64
• Power8/9
• Arm v8

---

许可证

UCX采用以下许可证：

• BSD3

---

我们的社区

• 项目官网
• ReadTheDocs
• Github
• 软件发布
• 邮件列表
• Twitter

---

贡献者协议与指南

为了向 UCX 作出贡献，请签署相应的 贡献者协议。

所有贡献者必须遵守“成员自愿共识标准”和“符合出口管制的贡献提交”政策。

提交贡献和更改时，请遵循这些 说明。

出版物

若在出版物中引用 UCX，请使用以下条目：

@inproceedings{shamis2015ucx,
  title={UCX: an open source framework for HPC network APIs and beyond},
  author={Shamis, Pavel and Venkata, Manjunath Gorentla and Lopez, M Graham and Baker, Matthew B and Hernandez, Oscar and Itigin, Yossi and Dubman, Mike and Shainer, Gilad and Graham, Richard L and Liss, Liran and others},
  booktitle={2015 IEEE 23rd Annual Symposium on High-Performance Interconnects},
  pages={40--43},
  year={2015},
  organization={IEEE}
}

若引用 UCX 官网，请使用以下条目：

@misc{openucx-website,
    title = {{统一通信 X 库}},
    key = {{{统一通信 X 库}}},
    howpublished = {{\url{http://www.openucx.org}}}
}

UCX 快速上手指南

Unified Communication X (UCX) 是一个专为现代高带宽、低延迟网络优化的通信框架，广泛应用于高性能计算（HPC）领域。它支持 RDMA (InfiniBand/RoCE)、TCP、GPU 直接通信等多种传输方式。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 CentOS, RHEL, Ubuntu 等主流发行版)
• CPU 架构: x86_64, Power8/9, Arm v8
• 关键依赖:
  • 若使用 InfiniBand 或 RoCE，需安装 rdma-core (版本 >= 28.0) 或 MLNX_OFED (版本 >= 5.0)。
  • 基础编译工具：gcc, make, autoconf, automake, libtool, binutils-devel。
  • 可选依赖：cuda-devel (GPU 支持), knem (共享内存加速)。

提示：国内用户若使用 Mellanox 网卡，建议通过厂商提供的国内镜像源安装 MLNX_OFED 驱动以获得最佳兼容性。

2. 安装步骤

您可以选择从源码编译安装，这是最灵活的方式。

方案 A：从 Release 包安装（推荐稳定版）

如果您已下载 release tarball (.tar.gz)：

# 解压并进入目录
tar -xzf ucx-<version>.tar.gz
cd ucx-<version>

# 配置、编译并安装
# 请将 /where/to/install 替换为您期望的安装路径
./contrib/configure-release --prefix=/where/to/install
make -j8
make install

方案 B：从 Git 仓库克隆（开发版或最新代码）

# 克隆仓库
git clone https://github.com/openucx/ucx.git
cd ucx

# 生成构建脚本
./autogen.sh

# 配置、编译并安装
./contrib/configure-release --prefix=/where/to/install
make -j8
make install

注意：

• 编译特定硬件支持（如特定网卡或 GPU）可能需要在 configure 阶段添加额外的命令行标志。
• 安装完成后，请记得将 $INSTALL_PATH/lib 添加到 LD_LIBRARY_PATH 环境变量中。

3. 基本使用

UCX 自带性能测试工具 ucx_perftest，可用于验证安装是否成功及测试网络性能。以下示例演示如何在单机上启动服务器和客户端进行延迟测试。

启动服务端

在终端 A 中运行（-c 0 表示绑定到 CPU 核心 0）：

./src/tools/perf/ucx_perftest -c 0

启动客户端

在终端 B 中运行，连接到服务端主机（将 <server-hostname> 替换为实际 IP 或主机名，-c 1 绑定到不同核心以避免资源竞争）：

./src/tools/perf/ucx_perftest <server-hostname> -t tag_lat -c 1

运行成功后，客户端将输出延迟测试结果。若需与 OpenMPI 或 MPICH 集成，请在配置这些 MPI 库时指定 --with-ucx=<install_path>。