[TENT][Sunrise] Add sunrise_link transport, platform support, and UT coverage

Integrate Sunrise platform/transport wiring across TENT runtime and examples, add SunriseLink end-to-end unit tests, and fix RDMA error logging pointer formatting to avoid crash during registration failure paths.

Made-with: Cursor

Author: liujialai

.gitignore

@@ -190,6 +190,16 @@ cmake-build-relwithdebinfo
 cmake-build-minsizerel
 cmake-build
 
+# Out-of-tree / developer-local CMake build directories
+build-sunrise/
+build-mc-te/
+
+# Local tooling (machine-specific; not part of upstream sources)
+.clangd
+
+# Temporary local notes (e.g. PR description drafts); keep out of version control
+/tmp_sunrise_pr_description.md
+
 libetcd_wrapper.h
 
 mooncake-wheel/mooncake/allocator.py

docs/source/zh_archive/sunrise_link_transport.md

@@ -0,0 +1,80 @@
+# Sunrise Link Transport
+
+## 概述
+Sunrise Link 是 Mooncake TENT 传输框架中的一个 GPU 传输后端。它通过 Tang Runtime（`tangrt`）提供设备内存分配、指针属性查询、Peer Copy 与 IPC 句柄相关能力，并在 TENT 中以 `SUNRISE_LINK` 传输类型注册。
+
+在运行时，当编译开启 `USE_SUNRISE` 且配置项 `transports/sunrise_link/enable=true` 时，`TransferEngineImpl` 会加载 Sunrise Link Transport。
+
+---
+
+## 新增依赖
+Sunrise Link Transport 在 Mooncake 基础依赖外，额外依赖 Tang Runtime：
+
+- **头文件路径**：`/usr/local/tangrt/include`
+- **库路径**：`/usr/local/tangrt/lib/linux-x86_64`
+- **动态库**：`libtangrt_shared.so`（运行时按默认安装路径加载）
+
+建议确认 `tangrt` 与 `ptml` 相关运行库可被动态链接器找到（例如通过 `LD_LIBRARY_PATH` 或系统库路径配置）。
+
+---
+
+## 构建与编译
+
+**前置条件**
+
+- 已安装可用的 Tang Runtime（默认安装到 `/usr/local/tangrt`）
+- 编译环境可访问 Mooncake 及其基础依赖
+
+**CMake 配置**
+
+```bash
+# 克隆 Mooncake 仓库
+git clone https://github.com/kvcache-ai/Mooncake.git
+cd Mooncake
+
+# 启用 TENT + Sunrise Link
+mkdir build && cd build
+cmake .. -DUSE_TENT=ON -DUSE_SUNRISE=ON
+
+# 编译
+make -j$(nproc)
+```
+
+---
+
+## 运行与测试
+
+`transfer_engine_bench` 支持 `sunrise_link` 协议，可用于基本连通性与性能验证。
+
+```bash
+# 终端 1：目标端（Target）
+./transfer_engine_bench \
+  --mode=target \
+  --protocol=sunrise_link \
+  --local_server_name=10.0.0.2 \
+  --metadata_server=P2PHANDSHAKE \
+  --gpu_id=0
+
+# 终端 2：发起端（Initiator）
+./transfer_engine_bench \
+  --mode=initiator \
+  --protocol=sunrise_link \
+  --metadata_server=P2PHANDSHAKE \
+  --segment_id=10.0.0.2:$PORT \
+  --gpu_id=0 \
+  --block_size=8388608 \
+  --batch_size=32
+```
+
+> 说明：当 `metadata_server=P2PHANDSHAKE` 时，目标端实际监听端口可能为动态分配端口。请以目标端日志中打印的实际端口替换 `--segment_id` 中的 `$PORT`。
+
+---
+
+## 配置项说明（TENT）
+
+Sunrise Link 支持通过配置文件调整行为，常用项包括：
+
+- `transports/sunrise_link/enable`：是否启用该传输（默认 `true`）
+- `transports/sunrise_link/async_memcpy_threshold`：异步拷贝阈值（单位 MiB）
+
+可根据业务负载与设备拓扑微调上述参数。

mooncake-transfer-engine/example/CMakeLists.txt

@@ -1,47 +1,65 @@
 set(WORKSPACE "${CMAKE_CURRENT_SOURCE_DIR}")
 
-if (USE_HIP)
+if(USE_HIP)
   file(GLOB EXAMPLE_SOURCES "*.cpp")
   hipify_files(EXAMPLE_SOURCES)
 
-  file(RELATIVE_PATH EXAMPLE_REL_PATH "${CMAKE_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}")
+  file(RELATIVE_PATH EXAMPLE_REL_PATH "${CMAKE_SOURCE_DIR}"
+       "${CMAKE_CURRENT_SOURCE_DIR}")
   set(WORKSPACE "${CMAKE_BINARY_DIR}/${EXAMPLE_REL_PATH}")
 endif()
 
 add_executable(transfer_engine_bench ${WORKSPACE}/transfer_engine_bench.cpp)
 target_link_libraries(transfer_engine_bench PUBLIC transfer_engine)
-if (USE_TENT)
-    target_link_libraries(transfer_engine_bench PUBLIC tent)
-    target_compile_definitions(transfer_engine_bench PRIVATE USE_TENT)
+if(USE_TENT)
+  target_link_libraries(transfer_engine_bench PUBLIC tent)
+  target_compile_definitions(transfer_engine_bench PRIVATE USE_TENT)
 endif()
 
-add_executable(transfer_engine_validator ${WORKSPACE}/transfer_engine_validator.cpp)
+add_executable(transfer_engine_sunrise_bench
+               ${WORKSPACE}/transfer_engine_sunrise_bench.cpp)
+target_link_libraries(transfer_engine_sunrise_bench PUBLIC transfer_engine)
+if(USE_TENT)
+  target_link_libraries(transfer_engine_sunrise_bench PUBLIC tent)
+  target_compile_definitions(transfer_engine_sunrise_bench PRIVATE USE_TENT)
+endif()
+
+add_executable(transfer_engine_validator
+               ${WORKSPACE}/transfer_engine_validator.cpp)
 target_link_libraries(transfer_engine_validator PUBLIC transfer_engine)
 
-add_executable(transfer_engine_bench_with_notify ${WORKSPACE}/transfer_engine_bench_with_notify.cpp)
+add_executable(transfer_engine_bench_with_notify
+               ${WORKSPACE}/transfer_engine_bench_with_notify.cpp)
 target_link_libraries(transfer_engine_bench_with_notify PUBLIC transfer_engine)
 
 add_executable(memory_pool ${WORKSPACE}/memory_pool.cpp)
 target_link_libraries(memory_pool PUBLIC transfer_engine)
 
-if (USE_ASCEND)
-    add_executable(transfer_engine_ascend_one_sided ${WORKSPACE}/transfer_engine_ascend_one_sided.cpp)
-    target_link_libraries(transfer_engine_ascend_one_sided PUBLIC transfer_engine)
+if(USE_ASCEND)
+  add_executable(transfer_engine_ascend_one_sided
+                 ${WORKSPACE}/transfer_engine_ascend_one_sided.cpp)
+  target_link_libraries(transfer_engine_ascend_one_sided PUBLIC transfer_engine)
 
-    add_executable(transfer_engine_ascend_perf ${WORKSPACE}/transfer_engine_ascend_perf.cpp)
-    target_link_libraries(transfer_engine_ascend_perf PUBLIC transfer_engine)
+  add_executable(transfer_engine_ascend_perf
+                 ${WORKSPACE}/transfer_engine_ascend_perf.cpp)
+  target_link_libraries(transfer_engine_ascend_perf PUBLIC transfer_engine)
 endif()
 
-if (USE_ASCEND_DIRECT)
-    add_executable(transfer_engine_ascend_direct_perf ${WORKSPACE}/transfer_engine_ascend_direct_perf.cpp)
-    target_link_libraries(transfer_engine_ascend_direct_perf PUBLIC ascendcl transfer_engine)
+if(USE_ASCEND_DIRECT)
+  add_executable(transfer_engine_ascend_direct_perf
+                 ${WORKSPACE}/transfer_engine_ascend_direct_perf.cpp)
+  target_link_libraries(transfer_engine_ascend_direct_perf
+                        PUBLIC ascendcl transfer_engine)
 endif()
 
-if (USE_ASCEND_HETEROGENEOUS)
-    add_executable(transfer_engine_heterogeneous_ascend_perf_initiator ${WORKSPACE}/transfer_engine_heterogeneous_ascend_perf_initiator.cpp)
-    target_link_libraries(transfer_engine_heterogeneous_ascend_perf_initiator PUBLIC transfer_engine)
+if(USE_ASCEND_HETEROGENEOUS)
+  add_executable(
+    transfer_engine_heterogeneous_ascend_perf_initiator
+    ${WORKSPACE}/transfer_engine_heterogeneous_ascend_perf_initiator.cpp)
+  target_link_libraries(transfer_engine_heterogeneous_ascend_perf_initiator
+                        PUBLIC transfer_engine)
 endif()
 
-if (USE_UBSHMEM)
-    target_link_libraries(transfer_engine_bench PUBLIC transfer_engine)
-endif()
+if(USE_UBSHMEM)
+  target_link_libraries(transfer_engine_bench PUBLIC transfer_engine)
+endif()

mooncake-transfer-engine/example/transfer_engine_bench.cpp

@@ -43,7 +43,7 @@
 #endif
 
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
 #include <cassert>
 
 #if defined(USE_MNNVL) || defined(USE_UBSHMEM)
@@ -88,7 +88,8 @@ DEFINE_string(mode, "initiator",
 DEFINE_string(operation, "read", "Operation type: read or write");
 
 DEFINE_string(protocol, "rdma",
-              "Transfer protocol: rdma|barex|tcp|efa|nvlink|nvlink_intra|hip");
+              "Transfer protocol: "
+              "rdma|barex|tcp|efa|nvlink|nvlink_intra|hip|sunrise_link");
 
 DEFINE_string(device_name, "mlx5_2",
               "Device name to use, valid if protocol=rdma");
@@ -107,7 +108,7 @@ DEFINE_uint32(report_precision, 2, "Report precision");
 DEFINE_string(backend, "classic", "Backend to use: classic|tent");
 
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
 DEFINE_bool(use_vram, true, "Allocate memory from GPU/NPU VRAM");
 DEFINE_bool(init_mem, true, "Initialize allocated memory");
 DEFINE_int32(gpu_id, 0,
@@ -119,7 +120,7 @@ using namespace mooncake;
 static void *allocateMemoryPool(size_t size, int buffer_id,
                                 bool from_vram = false) {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
     if (from_vram) {
         int gpu_id;
         if (FLAGS_gpu_id == -1) {
@@ -190,7 +191,7 @@ static void *allocateMemoryPool(size_t size, int buffer_id,
 
 static void freeMemoryPool(void *addr, size_t size) {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
     if (FLAGS_protocol == "nvlink" || FLAGS_protocol == "hip") {
 #ifdef USE_MNNVL
         if (FLAGS_use_vram) {
@@ -214,6 +215,10 @@ static void freeMemoryPool(void *addr, size_t size) {
 #endif
     } else {
 #ifndef USE_UBSHMEM
+        if (!FLAGS_use_vram) {
+            numa_free(addr, size);
+            return;
+        }
         // check pointer on GPU
         cudaPointerAttributes attributes;
         checkCudaError(cudaPointerGetAttributes(&attributes, addr),
@@ -271,10 +276,21 @@ static inline std::string calculateRate(uint64_t data_bytes, double duration) {
 volatile bool running = true;
 std::atomic<size_t> total_batch_count(0);
 
+// Ensure each worker thread has a valid GPU context before issuing transfers.
+static inline void setWorkerDeviceIfNeeded() {
+#if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
+    defined(USE_MACA) || defined(USE_SUNRISE)
+    if (FLAGS_use_vram && FLAGS_gpu_id >= 0) {
+        checkCudaError(cudaSetDevice(FLAGS_gpu_id),
+                       "Failed to set device in worker");
+    }
+#endif
+}
+
 // Common helper to determine buffer count based on GPU/NUMA configuration
 static int determineBufferCount() {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA)
+    defined(USE_MACA) || defined(USE_SUNRISE)
     if (FLAGS_use_vram) {
         int gpu_num;
         LOG(INFO) << "VRAM is used";
@@ -305,7 +321,7 @@ static std::vector<void *> allocateBuffers() {
     buffer_num = determineBufferCount();
     std::vector<void *> addr(buffer_num);
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
     for (int i = 0; i < buffer_num; ++i) {
         addr[i] = allocateMemoryPool(FLAGS_buffer_size, i, FLAGS_use_vram);
     }
@@ -328,7 +344,7 @@ static void freeBuffers(std::vector<void *> &addr) {
 // Helper to get location name for classic backend
 static std::string getLocationName(int buffer_id) {
 #if defined(USE_CUDA) || defined(USE_MUSA) || defined(USE_HIP) || \
-    defined(USE_MACA) || defined(USE_UBSHMEM)
+    defined(USE_MACA) || defined(USE_UBSHMEM) || defined(USE_SUNRISE)
     if (FLAGS_use_vram) {
         int name_suffix = (FLAGS_gpu_id == -1) ? buffer_id : FLAGS_gpu_id;
         return std::string(GPU_PREFIX) + std::to_string(name_suffix);
@@ -476,7 +492,8 @@ static Transport *installTransportFromFlags(TransferEngine *engine) {
         xport = engine->installTransport("efa", nullptr);
     } else if (FLAGS_protocol == "tcp" || FLAGS_protocol == "nvlink" ||
                FLAGS_protocol == "hip" || FLAGS_protocol == "nvlink_intra" ||
-               FLAGS_protocol == "ubshmem") {
+               FLAGS_protocol == "ubshmem" ||
+               FLAGS_protocol == "sunrise_link") {
         xport = engine->installTransport(FLAGS_protocol.c_str(), nullptr);
     } else {
         LOG(ERROR) << "Unsupported protocol: " << FLAGS_protocol;
@@ -644,6 +661,7 @@ void initiatorWorker(mooncake::tent::TransferEngine *engine,
                      void *addr,
                      const mooncake::tent::SegmentInfo &segment_info) {
     bindToSocket(thread_id % NR_SOCKETS);
+    setWorkerDeviceIfNeeded();
     mooncake::tent::Request::OpCode opcode;
     if (FLAGS_operation == "read")
         opcode = mooncake::tent::Request::READ;

mooncake-transfer-engine/include/cuda_alike.h

@@ -13,10 +13,12 @@
 #include "gpu_vendor/ubshmem.h"
 #elif defined(USE_MACA)
 #include "gpu_vendor/maca.h"
+#elif defined(USE_SUNRISE)
+#include "gpu_vendor/sunrise.h"
 #endif
 
 #if !defined(USE_HIP) && !defined(USE_MUSA) && !defined(USE_MLU) && \
-    !defined(USE_UBSHMEM) && !defined(USE_MACA)
+    !defined(USE_UBSHMEM) && !defined(USE_MACA) && !defined(USE_SUNRISE)
 #include <string>
 const static std::string GPU_PREFIX = "cuda:";
 #endif

mooncake-transfer-engine/include/gpu_vendor/sunrise.h

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <string>
+
+#include <tang_runtime_api.h>
+
+// SunriseLink uses CUDA-style location naming in metadata.
+const static std::string GPU_PREFIX = "cuda:";
+
+// Minimal CUDA-like API shim for benchmark paths.
+#define cudaError_t tangError_t
+#define cudaSuccess tangSuccess
+#define cudaGetErrorString tangGetErrorString
+
+#define cudaSetDevice tangSetDevice
+#define cudaGetDeviceCount tangGetDeviceCount
+
+#define cudaMalloc tangMalloc
+#define cudaFree tangFree
+#define cudaMemset tangMemset
+
+#define cudaPointerAttributes tangPointerAttributes
+#define cudaPointerGetAttributes tangPointerGetAttributes
+#define cudaMemoryTypeDevice tangMemoryTypeDevice
+#define cudaMemoryTypeHost tangMemoryTypeHost
+#define cudaMemoryTypeUnregistered tangMemoryTypeUnregistered
+
+#define cudaStreamSynchronize tangStreamSynchronize

mooncake-transfer-engine/tent/include/tent/common/types.h

@@ -79,9 +79,10 @@ enum TransportType {
     IOURING,
     TCP,
     AscendDirect,
+    SUNRISE_LINK,
     UNSPEC
 };
-const static int kSupportedTransportTypes = 8;
+const static int kSupportedTransportTypes = (int)TransportType::UNSPEC;
 
 struct MemoryOptions {
     Location location = kWildcardLocation;
@@ -107,4 +108,4 @@ struct SegmentInfo {
 }  // namespace tent
 }  // namespace mooncake
 
-#endif  // TENT_TYPES_H
+#endif  // TENT_TYPES_H