Rust CUDA加速计算库ug-cuda使用指南

概述

ug-cuda是一个Rust库，提供了对CUDA加速计算的支持，让开发者能够在Rust中利用GPU进行高性能并行计算。它封装了CUDA的底层API，提供了更符合Rust习惯的安全接口。

主要特性

• 安全的CUDA内存管理
• 设备管理接口
• 内核函数启动
• 流和事件管理
• 与Rust生态系统的良好集成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
ug-cuda = "0.1"

需要安装CUDA工具包(至少CUDA 10.0)和兼容的NVIDIA显卡驱动。

完整示例代码

1. 初始化CUDA环境

use ug_cuda::driver::{initialize, Device};

fn main() {
    // 初始化CUDA驱动
    initialize().unwrap();
    
    // 获取设备数量
    let device_count = Device::count().unwrap();
    println!("找到 {} 个CUDA设备", device_count);
    
    // 获取第一个设备
    let device = Device::get(0).unwrap();
    println!("使用设备: {}", device.name().unwrap());
}

2. 内存管理示例

use ug_cuda::memory::{DeviceBox, DeviceCopy};

fn main() {
    // 在设备上分配内存
    let mut dev_vec = DeviceBox::new(&[1.0f32, 2.0, 3.0]).unwrap();
    
    // 从设备内存复制回主机
    let mut host_data = [0.0f32; 3];
    dev_vec.copy_to(&mut host_data).unwrap();
    
    println!("从设备获取的数据: {:?}", host_data);
}

3. 完整向量加法示例

3.1 编写CUDA内核(kernel.cu)

extern "C" __global__ void add_vectors(const float* a, const float* b, float* c, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    if (i < n) {
        c[i] = a[i] + b[i];
    }
}

需要先编译为PTX文件：

nvcc --ptx -o kernel.ptx kernel.cu

3.2 Rust主程序

use ug_cuda::{driver::LaunchAsync, module::Module, memory::DeviceBox};

fn main() {
    // 初始化CUDA环境
    ug_cuda::driver::initialize().unwrap();
    
    // 加载编译好的CUDA模块
    let module = match Module::from_file("kernel.ptx") {
        Ok(m) => m,
        Err(e) => {
            eprintln!("无法加载PTX文件: {}", e);
            return;
        }
    };
    
    // 获取内核函数
    let kernel = match module.function("add_vectors") {
        Ok(k) => k,
        Err(e) => {
            eprintln!("找不到内核函数: {}", e);
            return;
        }
    };
    
    // 准备数据
    let a = [1.0f32, 2.0, 3.0];
    let b = [4.0f32, 5.0, 6.0];
    let mut c = [0.0f32; 3];
    
    // 分配设备内存
    let d_a = DeviceBox::new(&a).unwrap();
    let d_b = DeviceBox::new(&b).unwrap();
    let mut d_c = DeviceBox::new(&c).unwrap();
    
    // 启动内核
    unsafe {
        if let Err(e) = kernel.launch(
            &[(&d_a, &d_b, &mut d_c, &3)],
            1,  // gridDim
            3,  // blockDim
            0,  // sharedMemBytes
            None // stream
        ) {
            eprintln!("内核执行失败: {}", e);
            return;
        }
    }
    
    // 复制结果回主机
    if let Err(e) = d_c.copy_to(&mut c) {
        eprintln!("数据复制失败: {}", e);
        return;
    }
    
    println!("计算结果: {:?}", c); // 输出: [5.0, 7.0, 9.0]
}

4. 异步操作完整示例

use ug_cuda::{driver::{Stream, initialize}, memory::{DeviceBox, DeviceCopy}};

fn main() {
    // 初始化CUDA
    initialize().unwrap();
    
    // 创建CUDA流
    let stream = Stream::new().unwrap();
    
    // 准备数据
    let host_data = [1u32, 2, 3, 4];
    let mut dev_data = DeviceBox::new_uninit().unwrap();
    
    // 异步内存复制
    if let Err(e) = dev_data.copy_from_async(&host_data, &stream) {
        eprintln!("异步复制失败: {}", e);
        return;
    }
    
    // 等待流完成
    if let Err(e) = stream.synchronize() {
        eprintln!("流同步失败: {}", e);
        return;
    }
    
    println!("异步操作完成");
}

5. 性能计时完整示例

use ug_cuda::driver::{Event, initialize};

fn main() {
    // 初始化CUDA
    initialize().unwrap();
    
    // 创建事件
    let start = Event::new().unwrap();
    let stop = Event::new().unwrap();
    
    // 记录开始时间
    if let Err(e) = start.record(None) {
        eprintln!("无法记录开始事件: {}", e);
        return;
    }
    
    // 模拟需要计时的操作
    for _ in 0..1000 {
        // 一些计算...
    }
    
    // 记录结束时间
    if let Err(e) = stop.record(None) {
        eprintln!("无法记录结束事件: {}", e);
        return;
    }
    
    // 等待事件完成
    if let Err(e) = stop.synchronize() {
        eprintln!("事件同步失败: {}", e);
        return;
    }
    
    // 计算耗时
    match start.elapsed(&stop) {
        Ok(time) => println!("操作耗时: {} 毫秒", time),
        Err(e) => eprintln!("无法计算耗时: {}", e),
    }
}

性能提示

1. 尽量减少主机与设备间的数据传输
2. 使用合适的block和grid大小
3. 利用共享内存减少全局内存访问
4. 使用异步操作和流来重叠计算与数据传输

注意事项

• ug-cuda仍在活跃开发中，API可能会有变动
• 需要正确安装CUDA工具链
• 内核代码需要单独编译为PTX文件
• 错误处理很重要，CUDA操作可能会失败

通过ug-cuda，Rust开发者可以安全高效地利用GPU的计算能力，同时享受Rust的内存安全保证。