libcdma is a user-space library that provides Crystal Direct Memory Access (CDMA) functionality for high-performance memory operations within the UnifiedBus (UB) ecosystem. It enables asynchronous one-sided DMA operations for direct memory access between hosts and host/devices, leveraging the UB protocol stack for efficient data transfer and resource management.
UnifiedBus (UB) is a super-node-oriented interconnect protocol designed to unify IO, memory access, and communication between processing units. The UB architecture provides:
- High-performance data transfer across processing nodes
- Unified resource management through entity-granularity allocation
- Flexible resource composition for diverse workload requirements
- Efficient processing unit coordination via standardized protocol stack
Core UB Components:
- UBPU: Processing unit supporting the UB protocol stack
- UMMU: Memory management unit for address mapping and permission validation
- Entity: Basic unit for device resource allocation, identified by EID (Entity Identifier)
- UB Controller: Executes the UB protocol stack operations
CDMA serves as the DMA engine within the UB system, providing:
- Entity-granularity DMA resource allocation for secure, isolated memory operations
- UBMD-based memory addressing using EID + TokenID + UBA (Unified Bus Address)
- Asynchronous one-sided DMA operations for direct memory access between hosts and host/devices
- High-performance data movement optimized for UB interconnect topology
- One-sided host-to-host DMA: Initiator-driven asynchronous memory read/write between hosts without remote participation
- One-sided host-to-device DMA: Direct memory access from host to device memory space
- One-sided device-to-host DMA: Direct memory access from device to host memory space
- Atomic operations: Compare-And-Swap (CAS) and Fetch-And-Add (FAA) for synchronization
- Event-driven completion: Polling and interrupt-based completion notification
- Segment management: Local segment registration and remote segment import for flexible memory access
- Queue-based operation model: Priority-based queue allocation with configurable depth and event modes
- Processor Architecture: HiSilicon processors (refer to hardware documentation for specific models)
- DMA Hardware: Crystal DMA (CDMA) hardware unit must be present and functional
- Kernel Driver: The cdma kernel driver must be loaded and operational
- The driver provides the /dev/cdma device interface for user-space access
- Driver must support CDMA ioctl commands defined in the kernel ABI
- Kernel Headers: Linux kernel headers must be installed for compilation
- Required for cdma_abi.h which includes linux/types.h
- Headers provide kernel-user space ABI definitions
- libummu: Required external library for memory management utilities
- Available as a separate package in openEuler
- Linked dynamically at build time
- CMake: Version 3.5 or higher
- Required for building the library from source
- Standard C Library: POSIX-compliant C library with standard headers
- Kernel Module: cdma driver must be loaded: modprobe cdma
- Device Permissions: User must have appropriate permissions to access /dev/cdma device nodes
- Library Path: libcdma.so must be accessible via system library path
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
After installing the library (from RPM package or source build), here is a minimal example:
#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;
}For complete API documentation, see CDMA_API.md.
Please refer to the CDMA library API Doc for development.
For issues or questions, please contact:
- Email: dev@openeuler.org
- Vendor Support: Contact your hardware vendor's support channel for hardware-specific issues
We welcome contributions! Please follow openEuler contribution guidelines.
For detailed contribution guidelines, see the openEuler Contribution Guide.
This project is licensed under the MIT License.
- SPDX-License-Identifier: MIT
- Copyright: © 2025 HiSilicon Technologies Co., Ltd.
See the LICENSE file for the full license text.