# How ODS Performs GPU Detection on Linux and macOS: A Deep Dive into the Source Code

> Discover how ODS performs GPU detection on Linux and macOS by examining Bash scripts, sysfs, and sysctl data. Learn about the source code and fallback mechanisms for hardware detection.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: deep-dive
- Published: 2026-09-02

---

**ODS uses platform-specific Bash scripts to detect GPUs by reading sysfs entries on Linux and sysctl data on macOS, falling back to tools like nvidia-smi only when hardware files are unavailable.**

The Osmantic/ODS (Open-Source AI Stack) repository implements a deterministic, hardware-first detection system that identifies GPUs across operating systems to select appropriate backends and memory budgets. Unlike generic detection tools, ODS uses a cascading validation approach that inspects kernel interfaces before trusting high-level utilities, ensuring accurate identification even in containerized environments like WSL2.

## Linux GPU Detection Architecture

On Linux distributions, ODS executes the **`detect_gpu`** function defined in [`ods/installers/lib/detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/detection.sh) (line 776). This function populates environment variables—including `GPU_BACKEND`, `GPU_NAME`, `GPU_VRAM`, and `GPU_MEMORY_TYPE`—through a prioritized cascade of hardware checks.

### Jetson and Tegra Detection

The detection logic first checks for **NVIDIA Jetson** devices by inspecting Jetson-specific release files, device-tree markers, and the presence of `/sys/devices/gpu.0` (lines 881-894). When detected, ODS sets `GPU_BACKEND="jetson"` and derives `GPU_VRAM` from `/proc/meminfo` because Tegra systems use unified memory architecture where system RAM serves as graphics memory.

### Discrete NVIDIA GPU Detection

For discrete NVIDIA hardware, the script walks `/sys/class/drm/card*/device/vendor` searching for PCI vendor ID `0x10de` (lines 435-444). In WSL2 environments where sysfs entries may be missing, ODS falls back to `nvidia-smi` (lines 445-447). Upon confirmation, `nvidia-smi` provides the GPU name, VRAM capacity, device ID, and count (lines 449-468).

**Unified memory detection** occurs when `nvidia-smi` returns `[N/A]` for memory metrics—characteristic of newer Blackwell GPUs—triggering `GPU_MEMORY_TYPE="unified"` and allocating from system RAM instead (lines 560-572).

### Intel Arc GPU Support

ODS detects **Intel Arc** graphics by executing `lspci` and pattern-matching for "VGA … Intel … Arc" (line 600). For each match, the script reads vendor/device IDs from sysfs and determines VRAM from `lmem_total_bytes`, extracting marketing names through auxiliary parsing (lines 605-624).

### AMD GPU Identification

AMD detection gathers all `/sys/class/drm/card*/device` entries with vendor ID `0x1002` (lines 630-634). The logic differentiates **APU** configurations (large GTT, small dedicated VRAM) from discrete GPUs by comparing `mem_info_vram_total` and `mem_info_gtt_total` values (lines 558-566). For multi-GPU setups, ODS constructs a composite `GPU_NAME` (lines 590-603) and sets `HAS_NPU=true` when detecting Ryzen AI NPUs (lines 605-608).

### CPU-Only Fallback

When no GPU hardware matches the preceding checks, ODS gracefully degrades to `GPU_BACKEND="cpu"` and emits a warning (lines 620-627), ensuring the installer continues with CPU-optimized Docker overlays.

## macOS GPU Detection on Apple Silicon

macOS detection takes a fundamentally different approach since Apple Silicon machines use unified memory architecture without discrete GPUs. The detection logic resides in [`ods/installers/macos/lib/detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/macos/lib/detection.sh).

The **`get_apple_silicon_info`** function reads `uname -m` and `sysctl` data to identify the specific chip variant, performance cores, efficiency cores, and GPU core count (lines 18-54). Because **all system memory functions as VRAM** on Apple Silicon, the installer treats `SYSTEM_RAM_GB`—retrieved via `get_system_ram_gb` (lines 65-69)—as the graphics memory budget, aligning with the unified-memory handling in the Linux detection path.

## Integration and Usage

During the **pre-flight** phase ([`installers/phases/01-preflight.sh`](https://github.com/Osmantic/ODS/blob/main/installers/phases/01-preflight.sh)), the installer sources the appropriate detection library and executes `detect_gpu`. The resulting variables drive downstream decisions:

- Selecting Docker Compose overlays (`docker-compose.{amd,nvidia,apple}.yml`)
- Loading capability profiles (`load_capability_profile`)
- Calculating LLaMA.cpp CPU budgets (`calculate_llama_cpu_budget`)

The architecture maintains **pure-function-style Bash libraries** with no side effects beyond setting global variables, keeping platform-specific logic isolated between Linux sysfs-heavy operations and macOS sysctl queries.

```bash

# Linux example: Loading and running detection

source ods/installers/lib/detection.sh
detect_gpu

echo "Backend: $GPU_BACKEND"
echo "GPU: $GPU_NAME"
echo "VRAM (MB): $GPU_VRAM"
echo "Type: $GPU_MEMORY_TYPE"

```

```bash

# macOS example: Apple Silicon detection

source ods/installers/macos/lib/detection.sh
get_apple_silicon_info

echo "Chip: $APPLE_CHIP"
echo "GPU Cores: $APPLE_GPU_CORES"
echo "VRAM Budget: ${SYSTEM_RAM_GB}GB (unified)"

```

## Summary

- **ODS GPU detection** uses platform-specific scripts in [`ods/installers/lib/detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/detection.sh) (Linux) and [`ods/installers/macos/lib/detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/macos/lib/detection.sh) (macOS) to identify hardware before installation continues.
- The Linux implementation follows a deterministic cascade: Jetson → NVIDIA discrete → Intel Arc → AMD → CPU fallback, reading sysfs entries before falling back to tools like `nvidia-smi` or `lspci`.
- **Unified memory devices** (Jetson, Blackwell, Apple Silicon) trigger special handling where system RAM serves as the graphics memory budget via `GPU_MEMORY_TYPE="unified"`.
- Detection populates standard environment variables (`GPU_BACKEND`, `GPU_VRAM`, `HAS_NPU`) consumed by the pre-flight phase to select appropriate Docker overlays and model tiers.
- The system handles edge cases including WSL2 environments, multi-GPU setups, and CPU-only modes without failing the installation.

## Frequently Asked Questions

### How does ODS detect GPUs in WSL2 environments where sysfs might be incomplete?

When the standard Linux sysfs inspection fails to find vendor entries under `/sys/class/drm/`, ODS falls back to executing `nvidia-smi` directly (lines 445-447 in [`detection.sh`](https://github.com/Osmantic/ODS/blob/main/detection.sh)). This tool-based fallback provides GPU name, VRAM capacity, and device IDs even when the Windows Subsystem for Linux doesn't expose the full hardware interface, ensuring NVIDIA GPUs remain detectable across Windows development environments.

### What distinguishes APU from discrete AMD GPU detection in ODS?

ODS differentiates AMD APUs from discrete cards by comparing two sysfs values: `mem_info_vram_total` and `mem_info_gtt_total` (lines 558-566). APUs show large GTT (Graphics Translation Table) values relative to small dedicated VRAM, while discrete GPUs exhibit the opposite pattern. This distinction allows the installer to adjust memory allocation strategies accordingly.

### Why does ODS treat Apple Silicon memory as GPU VRAM?

Apple Silicon chips employ unified memory architecture where the CPU, GPU, and neural engine share a single memory pool without physical separation. Since ODS cannot distinguish "graphics memory" from system RAM on macOS, the detection script in [`ods/installers/macos/lib/detection.sh`](https://github.com/Osmantic/ODS/blob/main/ods/installers/macos/lib/detection.sh) uses the total system RAM (via `get_system_ram_gb`) as the graphics budget, setting the same unified-memory flags used for Jetson and Blackwell GPUs on Linux.

### What happens if ODS cannot detect any compatible GPU?

When no GPU matches the Jetson, NVIDIA, Intel, or AMD detection patterns, the `detect_gpu` function sets `GPU_BACKEND="cpu"` and emits a warning (lines 620-627), allowing the installation to proceed in CPU-only mode. This fallback ensures ODS remains functional on systems without discrete graphics or with unsupported hardware, though performance will be limited to CPU inference backends.