Multi-level cache pass-through acceleration solution.
Access rate limit exceeded. Please log in to continue.
MLCacheDirect README
1. 项目简介
MLCacheDirect 是一个基于 异步流水分片传输库 ,当前核心产物是:
- 动态库:
libos_transport.so - 对外头文件:
include/os_transport.h
它的主要职责是:
- 把一次大数据传输按固定大小切分为多个 chunk。
- 通过 URMA 提交
write with notify或recv请求。 - 用线程池按
request_id组织同一批 chunk 的后续处理。 - 在收到 completion 后,唤醒对应 worker 推进同一请求的后续任务。
- 为调用方提供一套“提交请求 -> 等待整批完成 -> 失败时取消剩余任务”的同步语义。
2. 当前目录结构
.
├── BUILD.bazel
├── CMakeLists.txt
├── WORKSPACE
├── build.sh
├── build_bazel.sh
├── include/
│ ├── os_transport.h
│ ├── os_transport_internal.h
│ ├── os_transport_log_internal.h
│ ├── os_transport_thread_pool.h
│ ├── os_transport_thread_pool_internal.h
│ └── os_transport_urma.h
├── rpm/
│ └── os-transport.spec
├── src/
│ ├── os_transport.c
│ ├── os_transport_log.c
│ ├── os_transport_thread_pool.c
│ └── os_transport_urma.c
├── test/
│ ├── test_os_transport_unit.c
│ └── test_thread_pool.c
├── third_party/
│ ├── BUILD.bazel
│ └── BUILD.urma
└── tools/
└── datasystem_test/
├── CMakeLists.txt
├── pipeline_h2d.cpp
└── README.md
说明:
- 根目录下的库代码 不依赖 CUDA runtime。
tools/datasystem_test/pipeline_h2d.cpp是上层联调用例,里面仍然会使用cudaMalloc/cudaMemcpy,用于验证“上层自己完成 H2D”的新模式。
3. 架构与职责边界
3.1 当前库负责什么
当前 MLCacheDirect 库负责:
- chunk 切分
- URMA 请求投递
- completion 事件解包
- 根据
request_id唤醒线程池 worker - 在 worker 中执行 send 侧的下一片发送任务
- 在 worker 中执行 recv 侧的上层回调
notify_callback - 请求级同步与资源回收
3.2 当前库不再负责什么
当前库不再直接负责:
cudaSetDevicecudaMalloccudaMemcpycudaEventRecord- CUDA stream / event 生命周期管理
这些动作现在应该由上层完成,例如:
- SDK
- datasystem client
- 业务自己的 GPU 数据搬运模块
4. 核心数据结构
4.1 os_transport_user_data_t
定义在 include/os_transport.h:
typedef union {
struct {
uint64_t chunk_type : 2;
uint64_t chunk_id : 6;
uint64_t chunk_size : 24;
uint64_t request_id : 32;
} bs;
uint64_t user_ctx;
} os_transport_user_data_t;
这是库中最关键的 completion 上下文,编码了:
request_id:整批请求的唯一标识chunk_id:当前是第几个 chunkchunk_size:当前 chunk 的字节数chunk_type:当前 chunk 的类型NOT_SPLITMIDDLE_CHUNKLAST_CHUNK
在 send 路径里,这份信息会被塞进 URMA 的 notify_data / user_ctx。
在 recv 路径里,os_transport_wake_up_task() 会从 completion 中把它解析出来,再透传给上层回调。
4.2 ost_buffer_info_t
typedef struct {
uint64_t addr;
urma_target_seg_t *tseg;
} ost_buffer_info_t;
表示一段 Host 侧缓冲区:
addr:缓冲区地址tseg:URMA 目标段信息
4.3 ost_device_info_t
typedef struct {
urma_jfr_t *jfr;
void *dst;
} ost_device_info_t;
虽然结构体名还叫 device_info,但就当前代码来说,它只为 recv 路径提供:
jfr:用于提交 URMA recv 的接收端资源dst:目标地址
注意:当前库里不会直接对 dst 做 cudaMemcpy。
它只是参与 chunk 地址计算,并在后续回调链路里让上层知道“这批数据是发往哪个目标地址逻辑范围的”。
4.4 notify_callback_t
typedef int (*notify_callback_t)(void *user_data);
这是当前 recv 路径的关键扩展点。
回调参数 user_data 实际上指向的是一份 os_transport_user_data_t 副本,副本内容由 os_transport_wake_up_task() 解析 completion 后,在 worker 执行前填充。
也就是说,上层在 notify_callback 里可以拿到:
request_idchunk_idchunk_sizechunk_type
然后自行决定后续动作,例如:
- 查到对应 chunk 的 host buffer / device ptr
- 触发
cudaMemcpyAsync - 做最后一个 chunk 的收尾通知
5. 代码模块说明
5.1 src/os_transport.c
这是库的主入口文件,主要负责:
- 对外 API 实现
- 参数校验
- 分片
- 构造任务组
- 注册到线程池
- completion 后的 worker 执行逻辑
- 等待请求完成并释放资源
其中最关键的两类 worker 任务是:
send worker
send_task_worker_func() 负责调用:
urma_write_with_notify()
把后续 chunk 继续发出去。
recv worker
recv_task_worker_func() 当前不做 CUDA 拷贝,而是:
- 从
recv_task_arg->notify_user_data取出 completion 元数据; - 调用上层注册的
notify_callback(&recv_task_arg->notify_user_data); - 根据回调返回值决定当前 chunk 是否成功;
- 更新整批任务的完成计数。
这正是“把 cudaMemcpy 移出去”后的核心落点。
5.2 src/os_transport_thread_pool.c
这是线程池实现,负责:
- worker 创建与销毁
- 任务队列管理
- pending request 队列管理
request_id -> worker绑定- 收到 completion 后按
request_id唤醒 worker - 批量任务提交
- 按请求取消未执行任务
当前设计的关键点:
- 同一个
request_id的任务会绑定到同一个 worker。 - worker 真正执行任务的时机由 completion 唤醒推进。
- 整批任务共享同一个
task_sync_t,主线程可以统一等待。
5.3 src/os_transport_urma.c
负责 URMA 封装:
urma_write_with_notify()urma_recv_with_notify()
send 路径通过 URMA_OPC_WRITE_IMM 发送,并携带 notify_data / user_ctx。
recv 路径负责向 jfr 投递 recv work request。
5.4 src/os_transport_log.c
负责日志注册与日志输出。
对外接口:
int os_transport_log_reg(int level, log_callback_t cb);
6. 分片机制
默认 chunk 大小定义在 include/os_transport.h:
#define DEFAULT_CHUNK_SIZE (2 * 1024 * 1024)
即默认 2MB。
6.1 send / recv 的共同分片规则
- 当
len <= DEFAULT_CHUNK_SIZE时,按单 chunk 处理。 - 当
len > DEFAULT_CHUNK_SIZE时,拆成多个 chunk。 - 每个 chunk 都会有自己的
chunk_id、chunk_size和chunk_type。
6.2 send 路径分片特点
大于 2MB 时:
- 主线程先把整批 send task 注册到线程池;
- 立即手动发送第一个 chunk;
- 后续 chunk 由 completion 驱动 worker 逐个继续发送;
- 调用方通过
wait_and_free_sync()等待整批完成。
6.3 recv 路径分片特点
大于 2MB 时:
- 主线程先切出所有 chunk;
- 为每个 chunk 注册一个 recv task;
- 调用
urma_recv_with_notify()为每个 chunk 投递 recv 请求; - completion 到来后,线程池按
request_id唤醒对应 worker; - worker 调用上层
notify_callback; - 调用方通过
wait_and_free_sync()等待整批完成。
这里要特别注意:
recv 路径的“完成”语义,当前指的是:
- URMA completion 已到达;
- 对应的
notify_callback已执行完成并返回。它不自动等价于“GPU 数据已经就绪”,除非你的
notify_callback自己实现了这部分保证。
7. 对外接口说明
7.1 初始化
uint32_t os_transport_init(urma_context_t *urma_ctx,
os_transport_cfg_t *ost_cfg,
void **handle);
作用:
- 初始化
os_transport_handle_t - 保存 URMA 上下文和配置
- 创建线程池
- 注册 JFC/JFCE
- 启动线程池
关键配置项:
typedef struct os_transport_cfg {
bool urma_event_mode;
uint8_t reserved1[3];
uint32_t worker_thread_num;
urma_jfce_t *jfce;
urma_jfc_t *jfc;
uint32_t reserved2[10];
} os_transport_cfg_t;
7.2 注册日志
int os_transport_log_reg(int level, log_callback_t cb);
用于注册日志回调。
7.3 send 接口
uint32_t os_transport_send(void *handle,
urma_jetty_info_t *jetty_info,
ost_buffer_info_t *local_src,
ost_buffer_info_t *remote_dst,
uint32_t len,
uint32_t server_key,
uint32_t client_key,
task_sync_t **ret_sync_handle);
作用:
- 切分 Host -> Host 发送数据
- 生成异步 send task
- 首片立即发送
- 后续分片由 notify 驱动 worker 继续发送
- 返回
task_sync_t供调用方等待整批完成
说明:
client_key最终会作为request_id写入 completion 透传字段。server_key会用于另一侧 completion/上下文区分。
7.4 recv 接口
uint32_t os_transport_recv(void *handle,
ost_buffer_info_t *host_src,
ost_device_info_t *device_dst,
uint32_t len,
uint32_t client_key,
task_sync_t **ret_sync_handle,
notify_callback_t notify_callback);
作用:
- 切分接收数据范围
- 为每个 chunk 注册 recv task
- 向 URMA 的
jfr投递 recv 请求 - completion 到来后回调上层
notify_callback - 返回
task_sync_t给调用方等待整批完成
这个接口和旧版最大的不同是:
notify_callback现在是 必填。
库自身不再在 recv worker 中做cudaMemcpy,而是把“收到 completion 之后怎么处理这片数据”的决定权交给上层。
7.5 completion 唤醒接口
int os_transport_wake_up_task(void *handle, void *cr_t);
作用:
- 从 URMA completion 中解析
user_data - 获取
request_id - 通知线程池唤醒对应 worker
- 把本次 completion 的
user_data作为透传信息传给后续 recv worker
7.6 等待并释放同步资源
uint32_t wait_and_free_sync(void *handle, task_sync_t *sync_handle);
作用:
- 等待当前请求整批任务结束
- 如果中途检测到任务未完整完成,则按
request_id取消剩余任务 - 释放同步对象、chunk 数组和任务组资源
7.7 取消指定请求的任务
uint32_t os_transport_cancel_tasks(void *handle, uint32_t request_id);
作用:
- 取消该
request_id对应的未执行任务
7.8 销毁句柄
uint32_t os_transport_destroy(void *handle);
作用:
- 销毁线程池
- 释放内部资源
8. 典型时序
8.1 send 路径时序
调用方
-> os_transport_send()
-> 切 chunk
-> 注册后续 task 到线程池
-> 立即发送第一个 chunk
远端/本端产生 completion
-> os_transport_wake_up_task()
-> 按 request_id 唤醒 worker
-> worker 执行下一片 send task
-> urma_write_with_notify()
调用方
-> wait_and_free_sync()
-> 等整批发送完成
8.2 recv 路径时序
调用方
-> os_transport_recv(..., notify_callback)
-> 切 chunk
-> 注册 recv task
-> 为每个 chunk 投递 urma_recv_with_notify()
URMA completion 到来
-> os_transport_wake_up_task()
-> 解析 request_id/chunk_id/chunk_size/chunk_type
-> 按 request_id 唤醒 worker
-> worker 执行 recv task
-> notify_callback(&os_transport_user_data_t_copy)
上层 notify_callback
-> 根据 chunk_id / chunk_size 查找业务上下文
-> 视需要执行 cudaMemcpy / cudaMemcpyAsync / 其他处理
调用方
-> wait_and_free_sync()
-> 等整批 recv task 完成
9. 如何在上层实现新的 H2D 模式
因为 cudaMemcpy 已经从库内移出,推荐上层把真正的 H2D 逻辑写进 notify_callback 或其后续调度流程中。
一个最简伪代码如下:
static int my_notify_callback(void *user_data)
{
os_transport_user_data_t *ud = (os_transport_user_data_t *)user_data;
if (!ud) {
return -1;
}
uint32_t request_id = ud->bs.request_id;
uint32_t chunk_id = ud->bs.chunk_id;
uint32_t chunk_size = ud->bs.chunk_size;
uint32_t chunk_type = ud->bs.chunk_type;
// 1. 根据 request_id 找到这次请求在上层保存的上下文
// 2. 根据 chunk_id 找到对应 host 地址和 device 地址
// 3. 执行 cudaMemcpyAsync(...) 或其他处理
// 4. 如有需要,在 LAST_CHUNK 时做额外收尾
(void)chunk_size;
(void)chunk_type;
return 0;
}
建议上层自己维护一份“请求上下文表”,至少包含:
request_id- 原始 host base address
- 原始 device base address
- 每个 chunk 的偏移
- stream / event
- 是否最后一片
- 是否需要聚合完成通知
这样 notify_callback 才能真正把 completion 元数据映射成实际的 GPU 拷贝动作。
10. 构建说明
10.1 CMake 构建
项目根目录提供 build.sh:
chmod +x build.sh
./build.sh
仅运行单元测试:
./build.sh -t
当前 build.sh 特点:
- 自动识别
x86_64/aarch64 - 构建目录为
build-<arch> - 默认会清理旧的 CMake/Bazel 构建产物
- 默认会生成 RPM
依赖:
cmakegccmakerpmbuild(打包时)liburma.so
10.2 Bazel 构建
项目根目录提供 build_bazel.sh:
chmod +x build_bazel.sh
./build_bazel.sh
运行测试:
./build_bazel.sh -t
清理构建缓存:
./build_bazel.sh -c
可通过环境变量指定 URMA 路径:
URMA_INCLUDE_DIR=/usr/include \
URMA_LIB_DIR=/usr/lib64 \
./build_bazel.sh
10.3 当前库的构建依赖说明
根目录库本身当前只依赖:
- URMA
- pthread
不依赖 CUDA runtime。
这一点可以从当前代码直接看出:
- 根目录
src/*.c没有包含cuda_runtime.h CMakeLists.txt没有链接CUDA::cudartBUILD.bazel没有引入 CUDA 依赖
只有 tools/datasystem_test/pipeline_h2d.cpp 这个上层联调用例还需要 CUDA。
11. RPM 产物
默认打包会生成:
- 主包:
os-transport-<version>-<release>.<arch>.rpm - 开发包:
os-transport-devel-<version>-<release>.<arch>.rpm
安装内容主要包括:
libos_transport.soinclude/os_transport.h
当前对外只安装公共头:
include/os_transport.h
内部头文件不对外导出。
12. 测试
12.1 单元测试
当前仓库内置两个测试:
test_thread_pooltest_os_transport_unit
运行方式:
./build.sh -t
或:
./build_bazel.sh -t
12.2 上层联调工具
tools/datasystem_test/pipeline_h2d.cpp 是一个联调/验证程序。
它的意义在于:
- 演示上层如何自己分配 device memory
- 演示上层如何在业务层处理 H2D
- 验证“库只做传输与通知,上层做 CUDA 拷贝”的新分工
这个工具的编译和使用说明见:
tools/datasystem_test/README.md
13. 使用建议与注意事项
13.1 recv 路径必须提供 notify_callback
当前 os_transport_recv() 的入参校验要求 notify_callback != NULL。
因为当前版本里,recv worker 的主要职责就是执行这个回调。
13.2 wait_and_free_sync() 只保证库侧任务完成
当前等待语义保证的是:
- URMA 任务提交与 completion 推进完成
- 线程池中对应 task 已完成
- 上层
notify_callback已返回
它不天然保证:
- GPU kernel 已完成
- CUDA stream 已同步
- device 数据一定已经可立即消费
这些保证要由你的 notify_callback 及其外部同步逻辑补齐。
13.3 request_id 是整批请求的关键键值
无论 send 还是 recv,request_id 都是整个任务编排的核心索引。
上层最好保证:
- 同时活跃的请求中
request_id唯一 - 能通过
request_id快速查到业务上下文
13.4 如果回调要做重活,建议上层自行控制并发
当前 notify_callback 运行在线程池 worker 中。
如果你在回调里直接做耗时很长的 H2D、同步等待或复杂业务逻辑,会占住该 worker。
因此更推荐的方式通常是:
- 在
notify_callback里只做轻量分发 - 真正的 CUDA 操作交给上层自己的线程/stream 调度模块
14. 一句话总结
当前版本的 MLCacheDirect 已经从“库内部负责 URMA + CUDA memcpy”的模型,调整成了“库负责 URMA 分片传输 + completion 唤醒 + 上层回调编排,而 H2D 具体执行由上层负责”的模型。
因此,在接入这个版本时,最重要的不是再去找库里的 cudaMemcpy,而是要在上层把这三件事补齐:
request_id -> 业务上下文映射;chunk_id -> host/device 偏移映射;notify_callback中的 H2D / 完成同步策略。