CXL-RPC

作品简介

CXL-RPC 是一个面向 CXL 共享内存的研究型 C++ RPC 运行时。它在同一套协议中提供消息发送（send）和共享 workload 直接调用（direct）两条执行路径，并通过 LB_AUTO 根据运行状态选择路径。两条路径调用同一个 workload symbol，共享同一份业务状态和 allocator，避免业务逻辑出现两份实现。

作品主要能力包括：

CXL 共享内存布局、node/session、消息槽和 owner-local allocator。
自包含 workload ELF loader、最小 C/C++ shim、共享锁与 SWCC。
LB_FORCE_SEND、LB_FORCE_DIRECT、LB_AUTO 三种调用策略。
无 CXL 设备时用于开发和验收的 shm 后端，以及真实 CXL 设备使用的 devdax 后端。
KV、Silo、推荐、图计算和 Search/RAG 五个可运行示例。
micro、real、sensitivity、ablation benchmark，以及 gRPC、brpc、Hydra-RPC baseline。

评审者可以先按下文的最短路径完成环境检查、Debug 编译和 KV Demo 运行；完整 Release、四后端 benchmark 与真实 CXL 部署均作为进阶流程单独说明。

获取源码

仓库已直接包含构建所需的第三方源码快照，不使用 git submodule。普通 clone 即可得到完整源码：

git clone --branch master --single-branch \
  https://cdn09022024.gitlink.org.cn/IwWoy6LJM4/dRPC.git CXL-RPC
cd CXL-RPC

这是赛事提交的正式源码入口。依赖版本、来源和许可证入口见 lib/README.md。检查脚本只验证当前环境，不会联网下载或安装：

./tools/setup/check-dependencies.sh --profile test

环境安装

项目要求 Linux、CMake 3.20+、Ninja 和支持 C++23 的编译器。自动安装脚本支持 Ubuntu 24.04 与 GCC 13；其它 Linux 发行版需要安装等价软件包，再运行依赖检查。

若只需编译、测试和运行 Demo，安装最小测试环境：

./tools/setup/system-setup.sh --profile test
./tools/setup/check-dependencies.sh --profile test

system-setup.sh 在非 root 用户下会通过 sudo apt-get 安装系统包。检查脚本是只读操作，不会联网下载或修改依赖。

若需要完整赛事 Release 与四后端 benchmark，再安装完整环境：

./tools/setup/system-setup.sh --profile all
./tools/setup/install-rpc-deps.sh
./tools/setup/check-dependencies.sh \
  --profile all --python /usr/bin/python3

system-setup.sh 只安装 apt 系统包；install-rpc-deps.sh 才会下载、编译并发布固定版本的 gRPC 和 brpc。其源码、构建与 staging 始终位于当前仓库的 build/rpc-deps/，不会在用户主目录创建构建目录；默认安装根为 /opt/rpc-deps。

若赛事机已经提供 /opt/rpc-deps，可以跳过安装器，直接校验：

./tools/setup/check-dependencies.sh \
  --profile all \
  --deps-root /opt/rpc-deps \
  --python /usr/bin/python3

默认系统依赖布局为：

/opt/rpc-deps/
├── manifests/
├── grpc/
│   ├── 1.81.0-gcc13-release/
│   │   ├── bin/{protoc,grpc_cpp_plugin}
│   │   ├── include/
│   │   └── lib/cmake/{grpc,protobuf,...}
│   └── current -> 1.81.0-gcc13-release/
└── brpc/
    ├── 1.17.0-pb3.21.12-gcc13-release/
    │   ├── include/
    │   └── lib/{libbrpc.a,pkgconfig/brpc.pc}
    └── current -> 1.17.0-pb3.21.12-gcc13-release/

赛事环境固定 gRPC 1.81.0 和 brpc 1.17.0。gRPC 使用安装包自带的 Protobuf； brpc 使用与其构建 ABI 匹配的系统 Protobuf。每次安装写入版本、commit、编译器和构建方式 manifest。可通过以下 CMake cache path 覆盖默认安装：

CXL_RPC_DEPS_ROOT
CXL_GRPC_ROOT
CXL_BRPC_ROOT

例如：

cmake --preset shm-release \
  -DCXL_RPC_DEPS_ROOT=/srv/rpc-deps

编译

默认开发流程使用仓库内的 shm-debug preset，backing 为 /dev/shm/cxl-rpc-shm，不要求 CXL 设备或 /dev/dax0.0：

./tools/setup/check-dependencies.sh --profile test

CC=gcc-13 CXX=g++-13 cmake --preset shm-debug
cmake --build --preset shm-debug --parallel
ctest --preset shm-debug

构建目录为当前仓库内的 build/shm-debug/。CTest 覆盖协议、allocator、ELF loader、RPC 生命周期、多进程和五个业务示例。

完整 Release 与四后端验收

赛事 Release 验收同时构建第一方 benchmark 与全部 baseline，并显式选择带绘图库的 Python。若已运行 system-setup.sh --profile all，使用：

./tools/setup/check-dependencies.sh \
  --profile all --python /usr/bin/python3

CC=gcc-13 CXX=g++-13 cmake --preset shm-release \
  -DCXL_BENCH_BASELINES='grpc;brpc;hydra' \
  -DCXL_BENCH_PYTHON_EXECUTABLE=/usr/bin/python3
cmake --build --preset shm-release
ctest --preset shm-release

CXL_BENCHMARK_RUNTIME_ACCEPTANCE=1 \
  /usr/bin/python3 tools/benchmark/quick_acceptance.py \
  --build-dir build-shm-release

最后一条命令运行四框架严格 quick acceptance；任一 backend 缺失、运行失败或缺图都会返回非零。当前开发机也可激活已有 cxl-bench，把上面两处 /usr/bin/python3 替换为 ${CONDA_PREFIX}/bin/python。

shm 能验证构建、同机多进程、workload 加载和 RPC 生命周期，但测得的是 tmpfs/DRAM 行为，不能报告为真实 CXL 性能。

preset	backend	build type	tests	benchmark	用途
`shm-debug`	shm	Debug	是	否	日常开发和完整正确性测试
`shm-release`	shm	Release	是	是	Release、benchmark 编译和 smoke
`devdax-release`	devdax	Release	只编译	默认否	真实 CXL 机器部署

运行 Demo

完成 shm-debug 配置后，可以单独构建并运行 KV Demo：

cmake --build --preset shm-debug --target kv_store_demo
./build/shm-debug/example/kv_store/kv_store_demo

程序会创建共享 backing，启动两个 endpoint，依次验证 put/get/update/erase、版本检查以及 send/direct/auto 调用路径；正常结束时返回 0。

其它 Demo target 为：

silo_mini_demo
reco_ads_rerank_demo
graph_neighborhood_scoring_demo
search_rag_rerank_demo

它们的可执行文件位于各自的 build/shm-debug/example/<name>/ 目录。五个 Demo 都会重建同一个共享 backing，因此必须串行运行。

双终端录制

五个示例都提供独立的 <name>_server 和 <name>_client，适合用两个终端录制完整的 RPC 交互。统一构建 Release 版本：

cmake --preset shm-release
cmake --build --preset shm-release --parallel --target \
  kv_store_server kv_store_client \
  silo_mini_server silo_mini_client \
  reco_ads_rerank_server reco_ads_rerank_client \
  graph_neighborhood_scoring_server graph_neighborhood_scoring_client \
  search_rag_rerank_server search_rag_rerank_client

每组都先在终端 1 启动 server，看到 READY 后再在终端 2 启动对应 client。例如：

# 终端 1
./build-shm-release/example/reco_ads_rerank/reco_ads_rerank_server

# 终端 2
./build-shm-release/example/reco_ads_rerank/reco_ads_rerank_client

client 打印 RESULT : PASS 后，在 server 终端按 Ctrl+C，等待 STOPPED cleanly。五个 server 都是 backing creator，并共用默认 /dev/shm/cxl-rpc-shm，因此每次只能运行一组；切换示例前必须先停止上一组 server。

构建和运行 benchmark

只构建第一方 CXL-RPC benchmark：

cmake --preset shm-release
cmake --build --preset shm-release --target \
  cxl_micro_bench cxl_real_bench cxl_sensitivity_bench cxl_ablation_bench

同时启用 gRPC 和 brpc 系统 baseline：

./tools/setup/system-setup.sh --profile all
./tools/setup/install-rpc-deps.sh
./tools/setup/check-dependencies.sh \
  --profile benchmark \
  --baselines grpc,brpc,hydra \
  --python /usr/bin/python3

CC=gcc-13 CXX=g++-13 cmake --preset shm-release \
  -DCXL_BENCH_BASELINES='grpc;brpc;hydra' \
  -DCXL_BENCH_PYTHON_EXECUTABLE=/usr/bin/python3
cmake --build --preset shm-release --target \
  cxl_micro_bench grpc_micro_bench brpc_micro_bench hydra_micro_bench \
  cxl_real_bench grpc_real_bench brpc_real_bench hydra_real_bench

全部可选 baseline 的列表是 grpc;brpc;hydra。Hydra-RPC 源码已包含在仓库中。

runner 不会自动配置或编译工程。完整绘图 quick smoke 使用：

CXL_BENCHMARK_RUNTIME_ACCEPTANCE=1 \
  /usr/bin/python3 tools/benchmark/quick_acceptance.py \
  --build-dir build-shm-release

正式采集、real workload 参数和绘图说明分别见 benchmark/README.md 与 tools/benchmark/README.md。

真实 CXL 部署

devdax-release 可在无设备主机上编译，但运行时会访问真实 device-dax：

cmake --preset devdax-release -DBUILD_BENCHMARK=ON
cmake --build --preset devdax-release

在设备主机启动任何 creator 前，必须检查 device mode、sysfs size/align、权限和窗口是否独占。完整流程见 assets/device-dax.md。不要用普通文件或软链接伪装 /dev/dax0.0。

文档

源码与文档冲突时，以当前源码、CMakeLists.txt 和 CMakePresets.json 为准。

许可证

项目自有源码采用 Apache License 2.0。lib/ 中的第三方源码快照继续遵循各自的许可证，具体入口见 lib/README.md。