Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:
gr-cuda is a GPU-accelerated signal processing OOT (Out-Of-Tree) module for GNU Radio 3.10+. It provides a specialized architecture where data movement between the host and GPU is handled automatically via a cuda_buffer system, allowing signal processing blocks to receive device pointers directly in their work() methods without manual cudaMemcpy calls. Sources: README.md:1-5
The module supports both C++ and Python-based GPU blocks. C++ blocks utilize a managed CUDA stream, while Python blocks leverage CuPy to achieve performance within 5% of hand-written CUDA C++ code. The system implements virtual memory management (VMM) to provide circular buffers on the device, mirroring standard GNU Radio CPU buffer behavior. Sources: README.md:7-16, README.md:82-89
System Requirements
The following software and hardware prerequisites must be met prior to installation:
| Requirement | Supported Version |
|---|---|
| NVIDIA GPU | CUDA-capable hardware |
| CUDA Toolkit | >= 10.2 |
| GNU Radio | >= 3.10 (> 3.10.12 recommended for fan-out stability) |
| CMake | >= 3.18 |
| Python Libraries | CuPy (for Python-based GPU blocks) |
Sources: README.md:20-27, CMakeLists.txt:14
Installation Process
The project uses a standard CMake-based build system. The build process automatically detects the GPU architecture of the host machine unless overridden by the user.
Build Workflow
The following diagram illustrates the standard build and installation sequence:
Sources: README.md:29-35, CMakeLists.txt:23-31
Manual Configuration
Users can customize the build using specific CMake flags:
- GPU Architecture: To target a specific GPU (e.g., Ampere), use
-DCMAKE_CUDA_ARCHITECTURES=86. By default, it is set to "native". - Conda/PyBOMBS: For environment-specific installs, set
-DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX". The build system also automatically detectsPYBOMBS_PREFIXfrom the environment. - Optimization: The build type defaults to "Release" to ensure optimization flags are enabled.
Sources: README.md:37-39, CMakeLists.txt:21-36, lib/CMakeLists.txt:88-95
Module Architecture & Components
The installation deploys several key components across the library and Python paths.
Component Breakdown
| Component | Description |
|---|---|
| gnuradio-cuda | The core shared library containing CUDA buffer logic and C++ kernels. |
| Python Bindings | Pybind11-generated wrappers for C++ blocks (e.g., add_python.cc, fft_python.cc). |
| CuPy Blocks | Pure Python GPU blocks such as fft_cupy.py and add_cupy.py. |
| GRC Blocks | GNU Radio Companion block definitions (YAML) for GUI-based flowgraphs. |
Sources: lib/CMakeLists.txt:46-54, python/cuda/CMakeLists.txt:21-30, python/cuda/bindings/CMakeLists.txt:25-42
Dependency Graph
The gnuradio-cuda library links against both GNU Radio and CUDA system libraries to enable its zero-copy pipeline.
Testing the Installation
After installation, it is critical to verify the environment using the provided Quality Assurance (QA) suite. The build system registers several tests covering C++ and Python functionality.
# Run all registered tests
ctest
# Or via ninja
ninja test
Sources: README.md:35, python/cuda/CMakeLists.txt:43-125
Key test categories include:
- Cupy Math: Validates Python-based GPU operations (
qa_cupy_math.py). - Sync Blocks: Tests basic GPU synchronization and rate-locked operations (
qa_add.py,qa_fft.py). - Stress Tests: Validates the zero-copy buffer under high load or complex fan-out conditions (
qa_long_race_stress.py).
Sources: python/cuda/CMakeLists.txt:49-125
Conclusion
The gr-cuda module provides a high-performance bridge between GNU Radio and NVIDIA GPUs. By adhering to the standard CMake installation process and ensuring CUDA/CuPy dependencies are satisfied, developers can quickly deploy GPU-accelerated signal processing chains that leverage both the ease of Python (via CuPy) and the efficiency of C++ (via cuda_buffer).