GXF 3.2.0 to 4.0 CUDA 12 路径 API 与数据结构增量分析

分析范围：以 isaac_ros_nitros 仓库中 release-3.2 与 release-4.0 分支对比为基础，聚焦 CUDA 12 路径 （gxf_x86_64_cuda_12_6、gxf_jetpack61）可用的公共 API 与数据结构变化。由于 GXF 核心头文件在各 CUDA 版本间共享，下列新增/修改的接口在 CUDA 12 构建上同样生效。

对比链接：https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nitros/compare/release-3.2...release-4.0

一、核心结论

4.0 在 CUDA 12 路径上的最大 API 增量集中在三块：

CUDA Green Context 支持（新组件、新驱动函数表、调度器集成）
CPU 线程实时调度与亲和性（SCHED_FIFO/SCHED_RR/SCHED_DEADLINE、CPU pinning）
内存与同步原语增强 （Managed Memory 类型、std::shared_mutex 并发保护、TimedJobList::remove）

二、全新 API / 组件 / 数据结构

2.1 CUDA Green Context（绿色上下文）

新增头文件 1 ：isaac_ros_gxf/gxf/core/include/gxf/std/cuda_green_context_pool.hpp

新增核心数据结构：

cpp 复制代码

// CUDA 驱动函数表，动态加载 green context 相关符号
struct CudaDriverFunctionTable {
  CUresult (*cuDeviceGet)(CUdevice*, int) = nullptr;
  CUresult (*cuGreenCtxGetDevResource)(CUgreenCtx, CUdevResource*, CUdevResourceType) = nullptr;
  CUresult (*cuGreenCtxCreate)(CUgreenCtx*, CUdevResourceDesc, CUdevice, unsigned int) = nullptr;
  CUresult (*cuDevSmResourceSplitByCount)(
      CUdevResource*, unsigned int*, const CUdevResource*, CUdevResource*, unsigned int,
      unsigned int) = nullptr;
  CUresult (*cuCtxFromGreenCtx)(CUcontext*, CUgreenCtx) = nullptr;
  CUresult (*cuDevResourceGenerateDesc)(
      CUdevResourceDesc*, CUdevResource*, unsigned int) = nullptr;
  CUresult (*cuDeviceGetDevResource)(
      CUdevice, CUdevResource*, CUdevResourceType) = nullptr;
  CUresult (*cuGetErrorName)(CUresult, const char**) = nullptr;
  CUresult (*cuGetErrorString)(CUresult, const char**) = nullptr;
};

// Green Context 池组件
class CudaGreenContextPool : public Component {
 public:
  Expected<CUgreenCtx> getGreenContext(uint32_t index);
  Expected<CUcontext> getCudaContext(uint32_t index);
  Expected<uint32_t> getPartitionSms(uint32_t index);
  Expected<uint32_t> getDefaultContextIndex();
  Expected<CUgreenCtx> getDefaultContext();
  Expected<uint32_t> getDeviceTotalSms(uint32_t index);

 private:
  Resource<Handle<GPUDevice>> gpu_device_;
  Parameter<uint32_t> green_context_flags_;
  Parameter<uint32_t> num_partitions_;
  Parameter<uint32_t> min_sm_count_;
  Parameter<std::vector<int32_t>> sms_per_partition_;
  Parameter<std::string> nvtx_identifier_;
  Parameter<int32_t> default_context_;

  std::vector<CUgreenCtx> green_context_;
  std::vector<CUcontext> cu_context_;
  uint32_t max_sm_count_ = 0;
  int32_t dev_id_ = -1;
  uint32_t default_index_ = 0;
  CudaDriverFunctionTable cuda_driver_fn_table_;
};

新增头文件 2 ：isaac_ros_gxf/gxf/core/include/gxf/std/cuda_green_context.hpp

cpp 复制代码

class CudaGreenContext : public Component {
 public:
  Expected<CUgreenCtx> greenContext() const;
  Expected<CUcontext> cudaContext();
  uint32_t index() const;
  CudaGreenContextPool* cudaGreenContextPool() const;

 private:
  Parameter<int32_t> index_;
  Parameter<Handle<CudaGreenContextPool>> cuda_green_context_pool_;
  Parameter<std::string> nvtx_identifier_;

  CUgreenCtx green_context_ = nullptr;
  CUcontext cuda_context_ = nullptr;
  uint32_t pool_index_ = 0;
};

2.2 CPU 实时调度与亲和性

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/cpu_thread.hpp

新增枚举与组件字段：

cpp 复制代码

enum class SchedulingPolicy : int32_t {
  kFirstInFirstOut = 1,  // SCHED_FIFO
  kRoundRobin = 2,       // SCHED_RR
  kDeadline = 6          // SCHED_DEADLINE
};

class CPUThread : public Component {
 public:
  std::vector<uint32_t> pinCores() const;
  Expected<SchedulingPolicy> schedPolicy() const;
  Expected<uint32_t> schedPriority() const;
  Expected<uint64_t> schedRuntime() const;    // SCHED_DEADLINE
  Expected<uint64_t> schedDeadline() const;   // SCHED_DEADLINE
  Expected<uint64_t> schedPeriod() const;     // SCHED_DEADLINE
  bool isRealtime() const;

 private:
  Parameter<bool> pin_entity_;
  Parameter<std::vector<uint32_t>> pin_cores_;
  Parameter<SchedulingPolicy> sched_policy_;
  Parameter<uint32_t> sched_priority_;
  Parameter<uint64_t> sched_runtime_;
  Parameter<uint64_t> sched_deadline_;
  Parameter<uint64_t> sched_period_;
};

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/scheduler.hpp

新增 Linux 调度系统调用封装：

cpp 复制代码

#ifdef __linux__
#ifdef __x86_64__
#define __NR_sched_setattr 314
#define __NR_sched_getattr 315
#endif
#ifdef __aarch64__
#define __NR_sched_setattr 274
#define __NR_sched_getattr 275
#endif

struct sched_attr {
  uint32_t size;
  uint32_t sched_policy;
  uint64_t sched_flags;
  int32_t sched_nice;
  uint32_t sched_priority;
  uint64_t sched_runtime;
  uint64_t sched_deadline;
  uint64_t sched_period;
};

static inline int sched_setattr(pid_t pid, const struct sched_attr* attr, unsigned flags);
static inline int sched_getattr(pid_t pid, struct sched_attr* attr,
                                unsigned int size, unsigned int flags);
#endif

2.3 内存类型扩展

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/allocator.hpp

cpp 复制代码

enum struct MemoryStorageType {
  kHost = 0,        // Host Pinned Memory
  kDevice = 1,      // Cuda Device Memory
  kSystem = 2,      // Heap Memory
  kCudaManaged = 3  // 新增：Cuda Managed Memory
};

对应新增字符串解析值 "Managed"。

2.4 Camera Utils 扩展新增 Codelet

头文件 ：isaac_ros_gxf_extensions/gxf_isaac_camera_utils/gxf/extensions/camera_utils/...

cpp 复制代码

// 相机信息同步组件
class CameraInfoSynchronization : public gxf::Codelet {
  gxf_result_t dropOldestMessagesIfQueueIsFull();
  gxf_result_t useLatestCameraInfo();

 private:
  gxf::Parameter<gxf::Handle<gxf::Receiver>> camera_message_rx_;
  gxf::Parameter<gxf::Handle<gxf::Receiver>> camera_info_message_rx_;
  gxf::Parameter<gxf::Handle<gxf::Transmitter>> camera_message_tx_;
  gxf::Parameter<gxf::Handle<gxf::Transmitter>> camera_info_message_tx_;
  gxf::Parameter<bool> use_latest_camera_info_;
  gxf::Parameter<bool> drop_old_messages_;
  gxf::Parameter<uint64_t> sync_policy_;
  std::vector<int64_t> camera_acq_times_;
  std::vector<int64_t> camera_info_acq_times_;
};

// 立体相机时间戳同步组件
class StereoCameraSynchronizer : public gxf::Codelet {
 private:
  gxf::Parameter<gxf::Handle<gxf::Receiver>> rx_right_camera_;
  gxf::Parameter<gxf::Handle<gxf::Receiver>> rx_left_camera_;
  gxf::Parameter<gxf::Handle<gxf::Transmitter>> tx_right_camera_;
  gxf::Parameter<gxf::Handle<gxf::Transmitter>> tx_left_camera_;
  gxf::Parameter<int64_t> max_timestamp_diff_;
  int64_t prev_left_unnamed_timestamp_, prev_right_unnamed_timestamp_;
  int64_t prev_left_named_timestamp_, prev_right_named_timestamp_;
};

2.5 CUDA 测试辅助组件

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/cuda/tests/green_context_with_smid.h

cpp 复制代码

struct SmidThreadInfo {
    int thread_id;
    int block_id;
    int thread_in_block;
    uint32_t smid;
    int block_dim_x;
    int grid_dim_x;
};

extern "C" {
    void test_every_thread_smid(int num_blocks, int threads_per_block, cudaStream_t stream,
                                SmidThreadInfo* h_thread_info);
    int32_t analyze_smid_results(std::vector<SmidThreadInfo*> ptr_thread_info,
                                 int threads_per_block, int num_blocks, int num_streams);
    int32_t test_smid_with_different_configurations(cudaStream_t* streams, int num_streams);
    int32_t collect_smid_from_kernel(int num_blocks, int threads_per_block, cudaStream_t stream,
                                     std::set<uint32_t>& unique_smids);
}

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/cuda/tests/test_cuda_helper.hpp

新增测试 Codelet：

cpp 复制代码

class GreenContextWithSmid : public Codelet { /* ... */ };
class CudaSMCount : public Codelet { /* ... */ };

三、已有 API / 数据结构的修改

3.1 CUDA Stream 与 Stream Pool

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/cuda/cuda_stream.hpp

cpp 复制代码

// 初始化接口新增 nvtx 标识与 green context
Expected<void> initialize(const std::string& nvtxIdentifier, uint32_t flags = 0,
                          int dev_id = -1, int32_t priority = 0,
                          CUgreenCtx green_ctx = nullptr);

// 新增驱动函数加载
 gxf_result_t loadDriverFunctions();

// 新增函数指针
CUresult (*fnCuGreenCtxStreamCreate)(CUstream*, CUgreenCtx, unsigned int, int32_t) = nullptr;

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/cuda/cuda_stream_pool.hpp

cpp 复制代码

class CudaStreamPool : public Allocator {
 private:
  Expected<Entity> createNewStreamEntity(const std::string& nvtx_identifier);

  // 新增参数
  Parameter<std::string> nvtx_identifier_;
  Parameter<Handle<CudaGreenContext>> cuda_green_context_;

  // 新增字段
  CUgreenCtx green_ctx_ = nullptr;
};

3.2 调度器（EventBasedScheduler）

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/event_based_scheduler.hpp

cpp 复制代码

class EventBasedScheduler : public Scheduler {
  // ScheduleEntity 新增字段
  struct ScheduleEntity {
    // ...
    CUcontext cuda_context_ = nullptr;
    CudaGreenContextPool* cuda_green_context_pool_ = nullptr;
  };

  // worker 线程入口新增 cpu_thread_cid 参数
  void workerThreadEntrance(ThreadPool* pool, int64_t thread_number,
                            gxf_uid_t cpu_thread_cid = kUnspecifiedUid);

  // 新增辅助方法
  gxf_result_t configureThread(gxf_uid_t thread_uid, gxf_uid_t cpu_thread_cid);
  gxf_result_t setCPUAffinity(const std::vector<uint32_t>& cpu_cores);
  bool isRealtimeCPUThread(gxf_uid_t cpu_thread_cid);
  gxf_result_t loadDriverFunctions();

  // 新增参数
  Parameter<std::string> worker_thread_name_id_;
  Parameter<std::vector<uint32_t>> pin_cores_;

  // 内部字段变化
  Entity default_thread_pool_entity_;
  ThreadPool* default_thread_pool_;

  // 死锁检测增强
  int64_t grace_end_timestamp_ = 0;
  bool deadlock_armed_ = false;

  // CUDA Driver API 函数指针
  CUresult (*fnCuCtxPushCurrent)(CUcontext) = nullptr;
  CUresult (*fnCuCtxPopCurrent)(CUcontext*) = nullptr;
};

3.3 线程池（ThreadPool）

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/resources.hpp

cpp 复制代码

class ThreadPool : public ResourceBase {
 public:
  struct Thread {
    gxf_uid_t uid;
    gxf_uid_t cpu_thread_cid;  // 新增
  };

  Expected<gxf_uid_t> addThread(gxf_uid_t key, gxf_uid_t cpu_thread_cid = kUnspecifiedUid);
  Expected<gxf_uid_t> addThread(gxf_uid_t key, const std::vector<uint32_t>& pin_cores);
  std::vector<uint32_t> coresToPin() const;

 private:
  Parameter<std::vector<uint32_t>> pin_cores_;
  std::map<gxf_uid_t, Thread> thread_pool_;
  static inline gxf_uid_t next_uid_ = 0;
};

3.4 内存分配器并发保护

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/cuda/stream_ordered_allocator.hpp

cpp 复制代码

class StreamOrderedAllocator : public CudaAllocator {
 private:
  mutable std::shared_mutex shared_mutex_;  // 替换 std::mutex
  // std::mutex mutex_;  // 已移除
};

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/rmm/rmm_allocator.hpp

cpp 复制代码

class RMMAllocator : public CudaAllocator {
 private:
  mutable std::shared_mutex shared_mutex_;  // 新增，替换 std::mutex

  // 成员命名规范化
  std::unique_ptr<rmm::mr::cuda_memory_resource> device_mr_;
  std::unique_ptr<rmm::mr::pool_memory_resource<...>> pool_mr_device_;
  std::unique_ptr<rmm::mr::pinned_memory_resource> pinned_mr_;
  std::unique_ptr<rmm::mr::pool_memory_resource<...>> pool_mr_host_;
  std::unordered_map<void*, std::pair<std::size_t, MemoryStorageType>> pool_map_;
};

3.5 定时任务列表

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/std/gems/timed_job_list/timed_job_list.hpp

cpp 复制代码

template <typename JobT>
class TimedJobList {
 public:
  // 新增：从队列中移除指定 job
  bool remove(JobT job);
};

3.6 参数解析器

头文件 ：isaac_ros_gxf/gxf/core/include/gxf/core/parameter_parser.hpp

cpp 复制代码

template <typename T>
struct ParameterParser<T> {
  static Expected<T> Parse(...) {
    // 新增：int8 / vector_int8 / vector_2d_int8 显式不支持
    if (!strcmp(key, "int8") || !strcmp(key, "vector_int8") || !strcmp(key, "vector_2d_int8")) {
      GXF_LOG_WARNING("type %s is not supported", key);
      return Unexpected{GXF_PARAMETER_INVALID_TYPE};
    }
    // ...
  }
};

3.7 几何库

头文件 ：isaac_ros_gxf_extensions/gxf_isaac_gems/gxf/gems/geometry/polygon.hpp

将废弃的 std::random_shuffle 替换为 std::shuffle + std::mt19937。

四、构建系统变化

头文件/文件 ：isaac_ros_gxf/CMakeLists.txt

cmake 复制代码

# 新增：允许覆盖 GXF core 库目录
option(GXF_CORE_LIB_DIR_OVERRIDE "Override path for GXF core library directory" "")

x86_64 默认库目录从 gxf_x86_64_cuda_12_6/ 改为 gxf_x86_64_cuda_13_0/；aarch64 增加 sbsa（SBSA CUDA 13.0）与 arm64（JetPack 7.0）分支判断。

注：CMake 默认安装路径改为 CUDA 13.0，但 gxf_x86_64_cuda_12_6/ 与 gxf_jetpack61/ 的二进制仍保留在包内，CUDA 12 构建可通过覆盖或选择旧路径使用。

五、移除/弃用的接口

以下头文件在 4.0 中被删除：

isaac_ros_gxf/gxf/core/include/gxf/ipc/grpc/grpc_client.hpp
isaac_ros_gxf/gxf/core/include/gxf/ipc/grpc/grpc_server.hpp
isaac_ros_gxf/gxf/core/include/gxf/ipc/http/http_client.hpp
isaac_ros_gxf/gxf/core/include/gxf/ipc/http/http_client_cpprest_impl.hpp
isaac_ros_gxf/gxf/core/include/gxf/ipc/http/http_ipc_client.hpp
isaac_ros_gxf/gxf/core/include/gxf/ipc/http/http_server.hpp

意味着 gRPC/HTTP IPC 相关 API 在 4.0 中不再以头文件形式提供。

六、按主题汇总

主题	新增/修改内容
CUDA Green Context	`CudaGreenContextPool`、`CudaGreenContext`、`CudaDriverFunctionTable`、调度器集成、stream 初始化支持 `CUgreenCtx`
CPU 实时调度	`SchedulingPolicy` 枚举、`CPUThread` 实时参数、`sched_attr` 结构体、`sched_setattr/sched_getattr` 包装、线程亲和性 pinning
线程池	`ThreadPool::Thread.cpu_thread_cid`、`addThread` 重载、`pin_cores_` 参数
内存类型	`MemoryStorageType::kCudaManaged`
并发保护	`StreamOrderedAllocator`、`RMMAllocator` 改用 `std::shared_mutex`
任务调度	`TimedJobList::remove()`
相机工具	`CameraInfoSynchronization`、`StereoCameraSynchronizer`
测试辅助	`SmidThreadInfo`、`GreenContextWithSmid`、`CudaSMCount`
参数系统	int8/vector_int8/vector_2d_int8 显式不支持
构建系统	`GXF_CORE_LIB_DIR_OVERRIDE`、默认库目录改 CUDA 13.0/JetPack 7.0
移除接口	gRPC/HTTP IPC 头文件全部删除

七、对 CUDA 12 用户的实际影响

Green Context 功能在 CUDA 12 上可用 ：只要驱动支持 CUgreenCtx 相关符号，即可使用新的 CudaGreenContextPool/CudaGreenContext 进行 SM 分区隔离。
实时调度需要 Linux 内核支持 ：SCHED_DEADLINE 等策略依赖 PREEMPT_RT 或相应内核配置。
CUDA 12.6 预编译库仍保留 ：4.0 同时打包了 gxf_x86_64_cuda_12_6 与 gxf_jetpack61 的 .so，CUDA 12 运行时不会缺失二进制支持。
IPC 头文件删除：若之前直接引用 GXF 的 gRPC/HTTP IPC 头文件，迁移到 4.0 时需要移除相关代码。