CXL-RPC

一、仓库内容

面向无跨机缓存一致性共享内存的 RPC 框架，支持共享缓冲区、复杂返回值、页管理和进程故障恢复，适用于 KV、缓存及共享对象服务。

• src/api：调用接口；src/common：配置、设备映射、同步与日志；src/shell：测试进程与实验调度。
• src/versions：CXL-RPC 实现及 CXLock、FineMem-Lock 对比实现；src/mimalloc、src/third_party：分配器适配及第三方依赖。
• demo：手动加法演示；tests/evaluation：功能验证与性能实验；tests/openeuler_rpc_vm：openEuler 虚拟机部署。
• docs、presentation：说明文档和答辩材料；根目录 CMakeLists.txt：基础客户端/服务端构建。

环境：x86-64 Linux、GCC 12+、CMake 3.18+、Python 3.10.12+、make、zlib 开发库。下面命令均从仓库根目录执行。

二、配置虚拟机并运行手动演示

宿主机需 KVM（WSL 须启用嵌套虚拟化）、至少 8 个逻辑 CPU、12 GiB 可用内存和 80 GiB 可用磁盘。Ubuntu 安装依赖并授予当前用户 KVM 权限：

sudo apt-get install qemu-system-x86 qemu-utils openssh-client curl acl util-linux
sudo setfacl -m u:$(id -un):rw /dev/kvm
mkdir -p .cache/openeuler-rpc-vm/images
curl -fL https://repo.openeuler.org/openEuler-24.03-LTS-SP2/virtual_machine_img/x86_64/openEuler-24.03-LTS-SP2-x86_64.qcow2.xz \
  -o .cache/openeuler-rpc-vm/images/openEuler-24.03-LTS-SP2-x86_64.qcow2.xz
python3 tests/openeuler_rpc_vm/host.py check
python3 tests/openeuler_rpc_vm/host.py prepare
sudo python3 tests/openeuler_rpc_vm/offline_bootstrap.py .cache/openeuler-rpc-vm server
sudo python3 tests/openeuler_rpc_vm/offline_bootstrap.py .cache/openeuler-rpc-vm client
python3 tests/openeuler_rpc_vm/host.py start server
python3 tests/openeuler_rpc_vm/host.py configure server
python3 tests/openeuler_rpc_vm/host.py start client
python3 tests/openeuler_rpc_vm/host.py configure client
python3 tests/openeuler_rpc_vm/host.py verify-shared
python3 tests/openeuler_rpc_vm/host.py initialize-rpc

若提示 KVM 权限丢失，重新执行上述 setfacl 后重试当前 start，已启动的虚拟机会保留。配置在 tests/openeuler_rpc_vm/config.json；脚本校验镜像 SHA256，在客体内安装依赖、编译演示并建立 devdax。仅首次执行初始化；已有部署不要重新下载镜像或初始化，重启用 python3 tests/openeuler_rpc_vm/host.py start all。

在三个终端分别执行以下命令，登录后执行对应脚本：

终端	宿主机命令	客体命令
服务端	python3 tests/openeuler_rpc_vm/host.py ssh server	~/rpc-vm/server.sh
守护进程	python3 tests/openeuler_rpc_vm/host.py ssh client	~/rpc-vm/daemon.sh
客户端	python3 tests/openeuler_rpc_vm/host.py ssh client	~/rpc-vm/client.sh

服务端按 Enter 回复；Ctrl-C 后重启服务端可观察恢复，不要再次 initialize-rpc。结束时退出演示并执行 python3 tests/openeuler_rpc_vm/host.py stop all，磁盘和共享数据保留。

三、配置虚拟机并运行自动功能验证

复用第二部分的两台虚拟机，增加一个独立的 6.25 GiB NVDIMM，不创建新系统盘、不覆盖演示数据：

python3 tests/openeuler_rpc_vm/host.py stop all
python3 tests/openeuler_rpc_vm/host.py prepare-functional
python3 tests/openeuler_rpc_vm/host.py start server
python3 tests/openeuler_rpc_vm/host.py configure-functional server
python3 tests/openeuler_rpc_vm/host.py start client
python3 tests/openeuler_rpc_vm/host.py configure-functional client
python3 tests/openeuler_rpc_vm/host.py functional             # 八类双虚拟机 RPC 功能验证
python3 tests/openeuler_rpc_vm/host.py stop all

八类功能报告写入 logs/rpc_test/dual_vm_*/。

四、编译并运行性能测试

在独占共享设备上运行；默认配置需要 140 GiB 共享内存及充足 CPU，可修改 tests/evaluation/microbenchmark/config.json 中的实验开关和规模：

bash tests/evaluation/microbenchmark/compile.sh
bash tests/evaluation/microbenchmark/test.sh /dev/dax0.0 all

四主机部署时，在四台主机分别把 all 替换为 0、1、2、3，先启动 0，再启动其他主机（不要等待主机 0 结束，主机 0 在其它主机运行前不会结束）；每个主机的布局配置必须相同。结果保存在 logs/，构建文件保存在 tests/evaluation/microbenchmark/build/。

KV 回放另需 Rust stable、libclang、libnuma、libhwloc、pkg-config 及联网下载 Rust 依赖。先执行 bash tests/evaluation/microbenchmark/compile_memcached.sh，再设置 tests/evaluation/microbenchmark/config.json 中 microbenchmark_tests.memcached 的 enabled、trace_dir。用户须提供 cluster12.000.parquet、cluster15.000.parquet、cluster31.000.parquet、cluster37.000.parquet，构建不下载轨迹。

从 CXLAlloc 作者提供的 Dropbox Parquet 压缩包下载轨迹：

bash tests/evaluation/microbenchmark/traces/dropbox.sh

脚本将四个 .parquet 文件放在 .cache/twitter-traces/，保留已有文件并清理临时压缩包。 将 tests/evaluation/microbenchmark/config.json 中的 microbenchmark_tests.memcached.trace_dir 设为该目录的绝对路径。轨迹数据无需提交到仓库。

五：无需虚拟机的功能测试

无需虚拟机的功能预检查及手动演示：

bash tests/evaluation/rpc_test/compile.sh
mkdir -p /tmp/cxlrpc-tests
bash tests/evaluation/rpc_test/functional.sh /tmp/cxlrpc-tests all
bash demo/demo_init.sh  # 仅首次；再在三个终端分别执行 daemon/server/client 脚本
bash demo/demo_daemon.sh
bash demo/demo_server.sh
bash demo/demo_client.sh

功能验证需要约 6 GiB 映射空间。

六、第三方代码与许可证

第三方组件、公开评估数据的归属和完整许可证入口见 THIRD_PARTY_NOTICES.md。各组件独立适用其上游许可。