How nvidia/aerial-cuda-accelerated-ran works
Purpose and Top-Level Shape
NVIDIA Aerial CUDA-Accelerated RAN is a GPU-accelerated 5G NR RAN SDK spanning PHY, MAC scheduling, control-plane integration, reference simulation, and Python/ML APIs. It is a multi-language systems repository: CUDA/C++ runtime components, MATLAB reference models, and Python bindings/tools. Root build orchestration starts at CMakeLists.txt; deployment-oriented builds use testBenches/phase4_test_scripts/build_aerial_sdk.sh.
GPU PHY Library (cuPHY)
cuPHY is the L1 compute core: a CUDA library exposing reusable GPU primitives and channel implementations for coding, modulation, synchronization, channel estimation/equalization, and uplink/downlink processing. The public/API boundary is centered on cuPHY/src/cuphy/cuphy_api.h and implementation context/device management in cuPHY/src/cuphy/cuphy_context.cpp. Channel-level composition wraps primitives into operational PHY functions in cuPHY/src/cuphy_channels/pusch_rx.cpp, cuPHY/src/cuphy_channels/pdsch_tx.cpp, and peers.
Key data flow: host-side callers create/configure cuPHY contexts, submit tensors/buffers and per-channel descriptors, CUDA kernels execute on GPUs, and decoded/processed results return through host-visible buffers.
PHY Control Plane and Real-Time Execution
cuPHY-CP/cuphydriver schedules per-slot PHY work, owns cell state, buffers, workers, GPU devices, and aggregation of channel PDUs. Its DL/UL split is explicit in cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp and cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp; PHY channel aggregators bridge incoming slot commands to cuPHY execution, e.g. cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp.
cuPHY-CP/cuphycontroller/src/cuphydriver.cpp configures and drives the PHY runtime from YAML-backed deployment profiles. This is the main control boundary between configuration/L2-facing applications and real-time GPU execution.
L2/MAC Scheduling and L2-to-PHY Boundary
cuMAC provides CUDA-accelerated L2 scheduling, with separate scheduling families for 4T4R and 64T64R/MU-MIMO. Representative allocation/scheduling engines are cuMAC/src/4T4R/multiCellScheduler.cu and cuMAC/src/64T64R/multiCellMuUeGrp.cu; its consumer-facing API is cuMAC/src/api.h.
L2-to-L1 messaging is handled by adapters rather than direct library coupling. The NVIDIA PHY adapter is in cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp; the SCF 5G FAPI adapter translates MAC/FAPI messages and builds slot commands in cuPHY-CP/scfl2adapter/lib/scf_5g_fapi/scf_5g_fapi_slot_commands.cpp. Shared-memory/event-driven NVIPC is the process boundary for multi-process deployments.
Fronthaul, RU, and Operations
The O-RAN fronthaul path is implemented by cuPHY-CP/aerial-fh-driver, with packet/network/GPU-transfer coordination in cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp and cuPHY-CP/aerial-fh-driver/lib/gpu_comm_doca.cu. The RU emulator provides a software radio-endpoint for integration and test flows: cuPHY-CP/ru-emulator/ru_emulator/main.cpp and cuPHY-CP/ru-emulator/ru_emulator/ru_emulator.cpp.
Operational management is supplied through gRPC/protobuf OAM services in cuPHY-CP/cuphyoam/src/cuphyoam.cpp and cuPHY-CP/cuphyoam/proto/scf_fapi_p9.proto. Metrics support includes a Prometheus backend at cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp.
Reference, Python, and Validation Ecosystem
5GModel/nr_matlab/nrSimulator.m and 5GModel/nr_matlab/runSim.m form the MATLAB 3GPP-oriented reference simulation and waveform/test-vector generation path. These models produce validation artifacts, including HDF5, that can feed cuPHY examples and integration tests.
pyaerial exposes cuPHY through pybind11 (pyaerial/pybind11/pycuphy_pybind.cpp) and higher-level Python PHY APIs (pyaerial/src/aerial/phy5g/api.py). It also includes ML-to-TensorRT export support at pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py.
Material runtime dependencies are NVIDIA CUDA GPUs and CUDA toolchain; deployment paths additionally target NVIDIA networking stacks through DOCA/DPDK/Rivermax, O-RAN fronthaul, gRPC, YAML configuration, HDF5 artifacts, and optionally TensorRT/ONNX for ML-enhanced PHY operations.
Main entry points: cuphydriver.cpp cuPHY controller · cuphy_api.h cuPHY API · pusch_rx.cpp PHY channels · nv_phy_driver_proxy.cpp NVIDIA PHY adapter
Components 22
GPU PHY
CUDA L1 library and channel processing.
- cuPHY API · Public host-side PHY context and submission boundary.
cuPHY/src/cuphy/cuphy_api.h - cuPHY context · Manages device execution context and resources.
cuPHY/src/cuphy/cuphy_context.cpp - PHY channels · Composes GPU primitives into operational UL and DL processing.
cuPHY/src/cuphy_channels/pusch_rx.cpp - CUDA GPUs · Executes cuPHY and cuMAC CUDA kernels.
Real-Time RAN
Slot execution, L2 adapters, fronthaul, and operations.
- cuMAC API
cuMAC/src/api.h - 4T4R scheduler
cuMAC/src/4T4R/multiCellScheduler.cu - 64T64R MU-MIMO
cuMAC/src/64T64R/multiCellMuUeGrp.cu - NVIDIA PHY adapter · Converts L2-facing calls into PHY driver requests.
cuPHY-CP/cuphyl2adapter/lib/nvPHY/nv_phy_driver_proxy.cpp - SCF FAPI adapter · Translates FAPI messages into slot commands.
- NVIPC · Shared-memory and event-driven multi-process boundary.
- cuPHY controller · Configures and drives the PHY runtime from deployment profiles.
cuPHY-CP/cuphycontroller/src/cuphydriver.cpp - DL slot map
cuPHY-CP/cuphydriver/src/downlink/slot_map_dl.cpp - UL slot map
cuPHY-CP/cuphydriver/src/uplink/slot_map_ul.cpp - PUSCH aggregator · Bridges uplink slot PDUs to cuPHY execution.
cuPHY-CP/cuphydriver/src/uplink/phypusch_aggr.cpp - O-RAN fronthaul · Coordinates network packets and GPU transfer.
cuPHY-CP/aerial-fh-driver/lib/fronthaul.cpp - RU emulator · Software radio endpoint for integration flows.
cuPHY-CP/ru-emulator/ru_emulator/main.cpp - OAM gRPC service
cuPHY-CP/cuphyoam/src/cuphyoam.cpp - Prometheus metrics
cuPHY-CP/gt_common_libs/aerial_metrics/src/prometheus_metrics_backend.cpp
Reference and Python
Validation models and Python/ML interfaces.
- MATLAB NR simulator · Generates reference waveforms and validation artifacts.
5GModel/nr_matlab/nrSimulator.m - pyaerial PHY API · High-level Python interface backed by pybind11 cuPHY bindings.
pyaerial/src/aerial/phy5g/api.py - TensorRT exporter
pyaerial/src/aerial/model_to_engine/exporters/tensorrt_exporter.py
Other components
- Root build
CMakeLists.txt
Connections 24
- Root build → cuPHY API: builds
- Root build → cuPHY controller: builds
- cuPHY API → cuPHY context: creates/configures
- cuPHY context → PHY channels: dispatches
- PHY channels → CUDA GPUs: executes kernels
- cuMAC API → 4T4R scheduler: selects
- cuMAC API → 64T64R MU-MIMO: selects
- 4T4R scheduler → NVIDIA PHY adapter: scheduling output
- 64T64R MU-MIMO → NVIDIA PHY adapter: scheduling output
- NVIDIA PHY adapter → NVIPC: multi-process transport
- SCF FAPI adapter → NVIPC: slot commands
- NVIPC → cuPHY controller: PHY requests
- cuPHY controller → DL slot map: drives DL slots
- cuPHY controller → UL slot map: drives UL slots
- UL slot map → PUSCH aggregator: UL PDUs
- DL slot map → cuPHY API: DL descriptors/buffers
- PUSCH aggregator → cuPHY API: UL descriptors/buffers
- O-RAN fronthaul → CUDA GPUs: GPU transfer
- O-RAN fronthaul → RU emulator: O-RAN traffic
- OAM gRPC service → cuPHY controller: operations control
- cuPHY controller → Prometheus metrics: runtime metrics
- MATLAB NR simulator → PHY channels: waveforms and HDF5 artifacts
- pyaerial PHY API → cuPHY API: pybind11 binding
- TensorRT exporter → pyaerial PHY API: ML engine export