libcdma

概述

libcdma 是一个用户态库，为 UnifiedBus (UB) 生态系统内的高性能内存操作提供 Crystal Direct Memory Access (CDMA) 功能。它支持主机与主机/设备之间的异步单边 DMA 操作，利用 UB 协议栈实现高效的数据传输和资源管理。

UnifiedBus (UB) 技术

UnifiedBus (UB) 是一种面向超级节点的互连协议，旨在统一处理单元之间的 IO、内存访问和通信。UB 架构提供：

• 跨处理节点的高性能数据传输
• 基于实体粒度分配的统一资源管理
• 满足多样化工作负载需求的灵活资源组合
• 通过标准化协议栈实现的高效处理单元协同

UB 核心组件：

• UBPU：支持 UB 协议栈的处理单元
• UMMU：用于地址映射和权限验证的内存管理单元
• 实体（Entity）：设备资源分配的基本单元，由 EID（实体标识符）标识
• UB 控制器：执行 UB 协议栈操作

CDMA 在 UB 中的作用

CDMA 作为 UB 系统中的 DMA 引擎，提供：

• 实体粒度的 DMA 资源分配，确保安全、隔离的内存操作
• 基于 UBMD 的内存编址，使用 EID + TokenID + UBA（统一总线地址）
• 异步单边 DMA 操作，支持主机与主机/设备之间的直接内存访问
• 针对 UB 互连拓扑优化的高性能数据移动

主要特性

• 单边主机到主机 DMA：发起方驱动的主机间异步内存读写，无需远程参与
• 单边主机到设备 DMA：从主机直接访问设备内存空间
• 单边设备到主机 DMA：从设备直接访问主机内存空间
• 原子操作：用于同步的比较交换（CAS）和取加（FAA）
• 事件驱动的完成机制：基于轮询和中断的完成通知
• 段管理：本地段注册和远程段导入，实现灵活的内存访问
• 基于队列的操作模型：支持优先级的队列分配，可配置深度和事件模式

需求说明

硬件需求

• 处理器架构：海思处理器（具体型号请参考硬件文档）
• DMA 硬件：必须配备并启用 Crystal DMA（CDMA）硬件单元

内核需求

• 内核驱动：必须加载并运行 cdma 内核驱动
  • 该驱动提供 /dev/cdma 设备接口供用户空间访问
  • 驱动必须支持内核 ABI 中定义的 CDMA ioctl 命令
• 内核头文件：必须安装 Linux 内核头文件以进行编译
  • 用于获取包含 linux/types.h 的 cdma_abi.h
  • 头文件提供内核-用户空间 ABI 定义

软件依赖

• libummu：用于内存管理工具的必要外部库
  • 在 openEuler 中作为独立软件包提供
  • 构建时动态链接
• CMake：3.5 或更高版本
  • 用于从源代码构建库
• 标准 C 库：符合 POSIX 标准的 C 库及标准头文件

运行时需求

• 内核模块：必须加载 cdma 驱动：modprobe cdma
• 设备权限：用户必须拥有访问 /dev/cdma 设备节点的适当权限
• 库路径：libcdma.so 必须可通过系统库路径访问

目录结构

libcdma/
├── include/               # Public API headers
│   └── cdma_u_lib.h       # Main library header
├── kernel_headers/        # Kernel ABI definitions  
│   └── cdma_abi.h         # Kernel-user space ABI
├── doc/                   # Documentation
│   └── CDMA_API.md        # Complete API reference
├── cdma_u_device.c        # Device discovery and management
├── cdma_u_device.h        
├── cdma_u_context.c       # Context creation/deletion
├── cdma_u_context.h       
├── cdma_u_jfs.c           # JFS (Jetty for Send) operations
├── cdma_u_jfs.h           
├── cdma_u_jfc.c           # JFC (Jetty for Completion) operations
├── cdma_u_jfc.h           
├── cdma_u_queue.c         # Queue management
├── cdma_u_queue.h         
├── cdma_u_segment.c       # Memory segment registration
├── cdma_u_segment.h       
├── cdma_u_event.c         # Event handling
├── cdma_u_event.h         
├── cdma_u_tp.c            # Transport point management
├── cdma_u_tp.h            
├── cdma_u_cmd.c           # Command processing
├── cdma_u_cmd.h           
├── cdma_u_db.c            # Doorbell operations
├── cdma_u_db.h            
├── cdma_u_common.c        # Common utilities
├── cdma_u_common.h        
├── cdma_u_log.c           # Logging functions
├── cdma_u_log.h           
├── cdma_u_types.h         # Type definitions
├── cdma_u_lib.c           # Library initialization
├── CMakeLists.txt         # Build configuration
├── LICENSE                # MIT License
└── README.md              # This file

头文件

cdma_u_lib.h

快速入门

安装库（通过RPM包或源码构建）后，以下是一个简单示例：

#include <stdio.h>
#include <cdma_u_lib.h>

int main(void) {
    uint32_t num_devices = 0;
    struct dma_device *dev_list = dma_get_device_list(&num_devices);
    
    if (!dev_list) {
        printf("No DMA devices found\n");
        return 1;
    }
    
    printf("Found %u DMA device(s)\n", num_devices);
    printf("First device: %s\n", dev_list[0].name);
    
    dma_free_device_list(dev_list, num_devices);
    return 0;
}

如需完整的 API 文档，请参见 CDMA_API.md。

注意事项

开发时请参考 CDMA 库的 API 文档。

技术支持

如遇问题或有疑问，请联系：

• 邮箱：dev@openeuler.org
• 厂商支持：硬件相关问题请通过硬件厂商的支持渠道联系

贡献代码

我们欢迎代码贡献！请遵循 openEuler 贡献指南。

详细的贡献指南，请参见 openEuler 贡献指南。

许可协议

本项目采用 MIT 许可协议。

• SPDX 许可标识符：MIT
• 版权所有：© 2025 海思半导体有限公司

完整的许可协议文本，请参见 LICENSE 文件。