Installing NVIDIA Aerial L1

Installing NVIDIA Aerial L1

A step-by-step guide to building and running the NVIDIA Aerial CUDA-Accelerated RAN testbed, the L1 (PHY) processing chain that runs on NVIDIA GPUs. Content mirrors the TOSSI-Foundation/nvidia_aerial_installation repository.

Overview

This guide provides step-by-step instructions for building and running the NVIDIA Aerial CUDA-Accelerated RAN testbed. The Aerial testbed is a complete software-defined radio access network (RAN) solution that runs on NVIDIA GPUs.

Official Documentation: NVIDIA Aerial Testbed Installation Guide

Prerequisites

Before starting the build and deployment, ensure you have:

Hardware Requirements

• NVIDIA GPU-enabled system (tested on DGX systems)
• Sufficient disk space (~50GB+)
• Network connectivity for downloading dependencies

Software Requirements

• Linux OS (Ubuntu 20.04/22.04 recommended)
• Docker and Docker Compose installed
• NVIDIA Container Runtime configured
• Git LFS support
• sudo access for installation

Network Configuration

• Identify your RU (Radio Unit) MAC address before installation
• Ensure network connectivity between host and container

Building the Aerial Testbed

Step 1: Clone the Repository

git clone --recurse-submodules https://github.com/NVIDIA/aerial-cuda-accelerated-ran.git ~/aerial-cuda-accelerated-ran
cd ~/aerial-cuda-accelerated-ran

The --recurse-submodules flag ensures all submodules are cloned recursively.

Step 2: Install Dependencies and Git LFS

cd ~/aerial-cuda-accelerated-ran/cubb_scripts/install/
sudo apt install make tmux git-lfs
git lfs pull

This step:

• Installs make, tmux, and Git LFS
• Pulls large binary files stored in Git LFS

Step 3: Create a tmux Session

tmux new-session -s "aerial-cuda-accelerated-ran" -n "installation"

A tmux session is recommended to handle long-running build processes and maintain session state if connection is lost.

Step 4: Build the Testbed

make all

This command:

• Compiles all necessary components
• May take 30-60 minutes depending on system
• Downloads and builds Docker images

Step 5: System Reboot

After the build completes:

sudo reboot

Wait for the system to fully restart.

Step 6: Set RU MAC Address and Final Build

After reboot, set your Radio Unit MAC address and run the final build step:

cd ~/aerial-cuda-accelerated-ran/cubb_scripts/install/
make build_aerial

Running the Aerial Testbed

Prerequisites for Running

1. Clone the nvidia_aerial_installation repository (if not already cloned):

git clone https://github.com/TOSSI-Foundation/nvidia_aerial_installation.git ~/nvidia_aerial_installation

This repository contains the docker-compose.yml file and orchestration configuration.

1. Navigate to the docker-compose directory:

cd ~/nvidia_aerial_installation

1. Verify docker-compose.yml exists with the aerial-l1 service configuration

Important: Directory Structure

• ~/aerial-cuda-accelerated-ran/ - Main NVIDIA Aerial source code and build artifacts
• ~/nvidia_aerial_installation/ - Orchestration repository containing docker-compose.yml

When running docker-compose, ensure you are in ~/nvidia_aerial_installation/, not ~/aerial-cuda-accelerated-ran/.

Step 1: Start the Testbed

docker-compose up -d

This command:

• Starts the aerial-l1 container in detached mode
• Mounts all necessary volumes (GPU, hugepages, modules, etc.)
• Runs with privileged: true for hardware access
• Executes /opt/nvidia/cuBB/run_l1.sh to start the L1 processing chain

Step 2: Verify Container is Running

docker ps | grep aerial-l1

Expected output shows the container running with ID and status.

Step 3: Monitor Logs

View real-time logs from the container:

docker logs -f aerial-l1

Expected log output should show:

• Initialization of L1 components
• PHY layer startup messages
• Eventually "L1 is ready!" message

Press Ctrl+C to stop following logs.

Step 4: Stop the Testbed

When finished:

docker-compose down

This cleanly stops and removes the container.

Docker Compose Configuration Details

Service: aerial-l1

The docker-compose.yml defines the main aerial-l1 service with these key configurations:

GPU Access

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities:
            - gpu

Allocates all available GPUs to the container.

Volume Mounts

Volume	Mount Point	Purpose
${HOME}/aerial-cuda-accelerated-ran	/opt/nvidia/cuBB/	Source code and binaries
/lib/modules	/lib/modules	Kernel modules
/dev/hugepages	/dev/hugepages	Huge page memory
/usr/src	/usr/src	Kernel source
../../../cmake_targets/share	/opt/cuBB/share	Shared resources
/var/log/aerial	/var/log/aerial	Log output directory

Note: The aerial-cuda-accelerated-ran volume uses ${HOME} which is automatically expanded by Docker Compose to your home directory. This ensures the correct path regardless of which user runs the container.

Environment Variables

• cuBB_SDK: Path to cuBB SDK in container
• AERIAL_LOG_PATH: Path where logs are written
• RU_MAC: Radio Unit MAC address (set at container startup)

Network Mode

• network_mode: host: Uses host network stack for direct network access
• privileged: true: Required for hardware access and privileged operations
• userns_mode: host: Uses host user namespace
• ipc: host: Uses host IPC namespace

Health Check

healthcheck:
  test: ["CMD-SHELL", 'grep -q "L1 is ready!" /tmp/phy.log && echo 0 || echo 1']
  interval: 20s
  timeout: 10s
  retries: 2

Monitors the PHY log for the "L1 is ready!" marker to confirm successful startup.

Viewing and Understanding Logs

Real-Time Log Monitoring

# Follow aerial-l1 container logs
docker logs -f aerial-l1

# View last 100 lines
docker logs --tail 100 aerial-l1

# View logs with timestamps
docker logs -f --timestamps aerial-l1

Log File Locations

Inside the container, logs are typically written to:

• /tmp/phy.log - PHY layer logs (monitored by health check)
• /var/log/aerial/ - Additional Aerial logs

Access from host:

tail -f /var/log/aerial/phy.log  # If mounted on host

Key Log Messages

Message	Meaning
L1 is ready!	System startup complete, ready for operation
Connected to RU	Radio Unit connection established
DuConnected	Downlink unit connection active
Error messages starting with ERR	Check configuration or connectivity

Configuration

RU MAC Address

The RU MAC address must be set correctly for proper operation. This can be done in two ways:

Option 1: Environment Variable in docker-compose.yml

environment:
  - RU_MAC=e8:c7:4f:1e:c7:4d

Option 2: Command-line Override

RU_MAC=<new-mac> docker-compose up -d

Custom Configuration

To modify Aerial configuration:

1. Edit configuration files in ~/aerial-cuda-accelerated-ran/cuPHY-CP/cuphycontroller/config/
2. Restart the container:

docker-compose restart aerial-l1

Docker Image Selection

Control which image version is used:

TAG=26-1-cubb docker-compose up -d
# or set REGISTRY for different registry
REGISTRY=your-registry/ TAG=custom-tag docker-compose up -d

Default: nvcr.io/nvidia/aerial/aerial-cuda-accelerated-ran:26-1-cubb

Troubleshooting

Container Fails to Start

1. Check Docker daemon:

docker ps
docker logs aerial-l1

1. Verify GPU access:

nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.0-runtime nvidia-smi

1. Check volume mounts:

docker inspect aerial-l1 | grep -A 20 Mounts

Health Check Failing

The health check looks for "L1 is ready!" in the PHY log:

# Check if log file exists
docker exec aerial-l1 ls -la /tmp/phy.log

# Check log contents
docker exec aerial-l1 tail -50 /tmp/phy.log

# Manually test health check condition
docker exec aerial-l1 grep -q "L1 is ready!" /tmp/phy.log && echo "PASS" || echo "FAIL"

No Connection to RU

1. Verify RU_MAC is correct:

docker inspect aerial-l1 | grep -A 10 "Env"

1. Check network connectivity:

docker exec aerial-l1 ping <ru-ip>
docker exec aerial-l1 ifconfig

1. Review eCPRI/FH logs for connection errors

GPU Memory Issues

If experiencing GPU OOM errors:

1. Reduce number of GPUs:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ['0', '1']  # Only use specific GPUs
          capabilities:
            - gpu

1. Check GPU memory usage:

nvidia-smi
docker exec aerial-l1 nvidia-smi

Build Fails with Git LFS

# Ensure Git LFS is installed
git lfs install
cd ~/aerial-cuda-accelerated-ran
git lfs pull

# Retry build
cd cubb_scripts/install/
make clean
make all

Advanced Operations

Container Inspection

Get container details:

docker inspect aerial-l1

Execute Commands in Container

# Interactive bash shell
docker exec -it aerial-l1 bash

# Run specific command
docker exec aerial-l1 <command>

Performance Monitoring

Monitor container resource usage:

docker stats aerial-l1

Cleanup and Rebuild

Remove all containers and images:

docker-compose down -v
docker system prune -a

Rebuild from scratch:

cd ~/aerial-cuda-accelerated-ran/cubb_scripts/install/
make clean
RU_MAC=<your-ru-mac> make all

Summary

Build Process

1. Clone repository with submodules
2. Install dependencies and Git LFS
3. Run make all (takes 30-60 minutes)
4. Reboot system
5. Set RU_MAC and run make all again

Running Process

1. Navigate to aerial-cuda-accelerated-ran directory
2. Run docker-compose up -d
3. Monitor with docker logs -f aerial-l1
4. Look for "L1 is ready!" in logs
5. Stop with docker-compose down

Key Files

• Docker Compose: docker-compose.yml
• Build Scripts: cubb_scripts/install/Makefile
• Configuration: cuPHY-CP/cuphycontroller/config/
• Logs: /var/log/aerial/ (host) or /tmp/phy.log (container)

References

• TOSSI nvidia_aerial_installation Repository
• Official NVIDIA Aerial Documentation
• NVIDIA Aerial GitHub Repository
• Docker Compose Reference
• NVIDIA Container Toolkit

Support

For issues and questions:

• Check NVIDIA Aerial documentation
• Review container logs for error messages
• Verify hardware prerequisites and network configuration
• Consult the troubleshooting section above