# DKMS and NVIDIA Support in Particle-OS

## Overview

Particle-OS supports DKMS (Dynamic Kernel Module Support) and NVIDIA drivers, following the successful patterns established by uBlue-OS. This enables users to install proprietary drivers, kernel modules, and other software that requires kernel compilation while maintaining the immutable system architecture.

## Why DKMS Support is Essential

### Desktop Use Cases
- **NVIDIA Gaming**: Proprietary NVIDIA drivers for optimal gaming performance
- **Hardware Support**: Custom kernel modules for specialized hardware
- **Virtualization**: VMware, VirtualBox, and other virtualization tools
- **Network Cards**: Custom drivers for enterprise network adapters
- **Storage Controllers**: RAID controllers and specialized storage hardware

### uBlue-OS Inspiration
uBlue-OS successfully implements DKMS support through:
- **NVIDIA Variants**: Dedicated builds with NVIDIA drivers pre-installed
- **DKMS Integration**: Automatic kernel module compilation and installation
- **Atomic Updates**: DKMS modules are rebuilt when kernel updates occur
- **Rollback Safety**: Failed DKMS builds don't break the system

## Particle-OS DKMS Architecture

### 1. DKMS Layer Management

```bash
# Create a DKMS-enabled layer
apt-layer ubuntu-base/24.04 dkms-base/24.04 dkms

# Install NVIDIA drivers with DKMS
apt-layer dkms-base/24.04 nvidia-gaming/24.04 nvidia-driver-535

# Install other DKMS modules
apt-layer dkms-base/24.04 vmware/24.04 open-vm-tools-dkms
```

### 2. Kernel Synchronization

```bash
# DKMS automatically rebuilds when kernel updates
apt-layer ubuntu-base/24.04 kernel-update/24.04 linux-generic-hwe-24.04

# Verify DKMS modules are rebuilt
apt-layer --dkms-status
```

### 3. NVIDIA Support Variants

#### Particle-OS Bazzite Gaming (NVIDIA)
- **Base**: Ubuntu 25.04 with latest Mesa drivers
- **NVIDIA Support**: Pre-installed NVIDIA drivers via DKMS
- **Gaming Optimizations**: Steam, Wine, Proton, gaming peripherals
- **Performance Tuning**: NVIDIA-specific performance optimizations

#### Particle-OS Corona Gaming (NVIDIA)
- **Base**: Ubuntu 24.04 LTS with KDE Plasma
- **NVIDIA Support**: Pre-installed NVIDIA drivers via DKMS
- **Desktop Gaming**: KDE Plasma gaming environment
- **Stability Focus**: LTS base for long-term stability

## Implementation Strategy

### Phase 1: DKMS Infrastructure

#### 1.1 DKMS Layer Support
```bash
# Add DKMS support to apt-layer
apt-layer --add-dkms-support ubuntu-base/24.04

# Install DKMS packages
apt-layer ubuntu-base/24.04 dkms-base/24.04 \
  dkms \
  build-essential \
  linux-headers-generic
```

#### 1.2 Kernel Header Management
```bash
# Automatic kernel header installation
apt-layer --install-kernel-headers

# Verify kernel headers match running kernel
apt-layer --verify-kernel-headers
```

### Phase 2: NVIDIA Driver Support

#### 2.1 NVIDIA Repository Integration
```bash
# Add NVIDIA repository
apt-layer --add-repo nvidia

# Install NVIDIA drivers
apt-layer dkms-base/24.04 nvidia-gaming/24.04 \
  nvidia-driver-535 \
  nvidia-settings \
  nvidia-prime
```

#### 2.2 NVIDIA Variant Creation
```bash
# Create NVIDIA gaming variant
apt-layer create-variant nvidia-gaming \
  --base ubuntu-base/24.04 \
  --add dkms nvidia-driver-535 steam wine \
  --description "Gaming variant with NVIDIA support"
```

### Phase 3: Advanced DKMS Features

#### 3.1 DKMS Module Management
```bash
# List installed DKMS modules
apt-layer --dkms-list

# Rebuild specific DKMS module
apt-layer --dkms-rebuild nvidia-driver-535

# Remove DKMS module
apt-layer --dkms-remove virtualbox-dkms
```

#### 3.2 DKMS Atomic Operations
```bash
# Atomic DKMS installation
apt-layer --atomic-dkms-install nvidia-driver-535

# Rollback failed DKMS installation
apt-layer --dkms-rollback
```

## Technical Implementation

### DKMS Integration with apt-layer

#### 1. DKMS Hook System
```bash
# DKMS hooks for kernel updates
/etc/apt-layer/hooks/dkms-pre-install.sh
/etc/apt-layer/hooks/dkms-post-install.sh
/etc/apt-layer/hooks/dkms-pre-remove.sh
/etc/apt-layer/hooks/dkms-post-remove.sh
```

#### 2. Kernel Version Tracking
```bash
# Track kernel versions for DKMS
/var/lib/particle-os/dkms/kernel-versions.json

# Example content:
{
  "current": "5.15.0-56-generic",
  "installed": ["5.15.0-56-generic", "5.15.0-55-generic"],
  "dkms_modules": {
    "nvidia-driver-535": ["5.15.0-56-generic"],
    "virtualbox-dkms": ["5.15.0-56-generic"]
  }
}
```

#### 3. DKMS Build Environment
```bash
# Containerized DKMS builds
apt-layer --dkms-build-container nvidia-driver-535

# Isolated build environment
/var/lib/particle-os/dkms/build-environments/
```

### NVIDIA-Specific Optimizations

#### 1. NVIDIA Prime Support
```bash
# Configure NVIDIA Prime
apt-layer --configure-nvidia-prime

# Switch between integrated and discrete graphics
apt-layer --gpu-switch integrated
apt-layer --gpu-switch nvidia
```

#### 2. Gaming Performance Tuning
```bash
# Apply gaming optimizations
apt-layer --apply-gaming-tweaks

# Configure Steam and Wine
apt-layer --configure-gaming-environment
```

#### 3. NVIDIA Settings Integration
```bash
# Install NVIDIA settings
apt-layer --install-nvidia-settings

# Configure NVIDIA settings
apt-layer --configure-nvidia-settings
```

## Variant Definitions

### Particle-OS Bazzite Gaming (NVIDIA)
```json
{
  "name": "particle-os-bazzite-gaming-nvidia",
  "base": "ubuntu-base/25.04",
  "description": "Gaming-focused variant with NVIDIA support",
  "packages": [
    "dkms",
    "build-essential",
    "linux-headers-generic",
    "nvidia-driver-535",
    "nvidia-settings",
    "nvidia-prime",
    "steam",
    "wine",
    "lutris",
    "gamemode",
    "mangohud"
  ],
  "repositories": [
    "nvidia",
    "steam"
  ],
  "configurations": [
    "gaming-performance",
    "nvidia-prime",
    "steam-integration"
  ]
}
```

### Particle-OS Corona Gaming (NVIDIA)
```json
{
  "name": "particle-os-corona-gaming-nvidia",
  "base": "ubuntu-base/24.04",
  "description": "KDE Plasma gaming variant with NVIDIA support",
  "packages": [
    "dkms",
    "build-essential",
    "linux-headers-generic",
    "nvidia-driver-535",
    "nvidia-settings",
    "nvidia-prime",
    "kde-plasma-desktop",
    "steam",
    "wine",
    "gamemode"
  ],
  "repositories": [
    "nvidia",
    "steam"
  ],
  "configurations": [
    "kde-gaming",
    "nvidia-prime",
    "steam-integration"
  ]
}
```

## Usage Examples

### Basic NVIDIA Installation
```bash
# Create NVIDIA gaming variant
apt-layer create-variant nvidia-gaming \
  --base ubuntu-base/24.04 \
  --add dkms nvidia-driver-535 steam

# Deploy the variant
bootc-alternative.sh deploy nvidia-gaming/24.04
```

### DKMS Module Management
```bash
# Install VirtualBox with DKMS
apt-layer --live-install virtualbox-dkms

# Check DKMS status
apt-layer --dkms-status

# Rebuild DKMS modules after kernel update
apt-layer --dkms-rebuild-all
```

### Gaming Environment Setup
```bash
# Apply gaming optimizations
apt-layer --apply-gaming-tweaks

# Configure Steam
apt-layer --configure-steam

# Install gaming tools
apt-layer --live-install gamemode mangohud
```

## Troubleshooting

### Common DKMS Issues

#### 1. Kernel Header Mismatch
```bash
# Fix kernel header mismatch
apt-layer --fix-kernel-headers

# Reinstall kernel headers
apt-layer --reinstall-kernel-headers
```

#### 2. DKMS Build Failures
```bash
# Check DKMS build logs
apt-layer --dkms-logs nvidia-driver-535

# Clean DKMS build environment
apt-layer --dkms-clean nvidia-driver-535

# Rebuild with verbose output
apt-layer --dkms-rebuild nvidia-driver-535 --verbose
```

#### 3. NVIDIA Driver Issues
```bash
# Check NVIDIA driver status
apt-layer --nvidia-status

# Reinstall NVIDIA drivers
apt-layer --reinstall-nvidia-drivers

# Switch to integrated graphics
apt-layer --gpu-switch integrated
```

### Recovery Procedures

#### 1. DKMS Rollback
```bash
# Rollback failed DKMS installation
apt-layer --dkms-rollback

# Restore previous working state
apt-layer --restore-dkms-state
```

#### 2. NVIDIA Driver Recovery
```bash
# Boot to recovery mode
apt-layer --boot-recovery

# Remove problematic NVIDIA drivers
apt-layer --remove-nvidia-drivers

# Reinstall from scratch
apt-layer --reinstall-nvidia-drivers
```

## Future Enhancements

### 1. Automated DKMS Testing
- Automated testing of DKMS modules in containers
- Integration testing with different kernel versions
- Performance benchmarking of DKMS modules

### 2. Advanced NVIDIA Features
- CUDA support for machine learning workloads
- Multi-GPU support for advanced gaming setups
- NVIDIA RTX features and ray tracing support

### 3. Enterprise DKMS Support
- Corporate DKMS module management
- Centralized DKMS policy enforcement
- Automated DKMS compliance reporting

## Conclusion

DKMS and NVIDIA support are essential for Particle-OS to compete with uBlue-OS in the desktop gaming and professional workstation markets. By implementing a comprehensive DKMS system with NVIDIA driver support, Particle-OS can provide the same level of hardware compatibility while maintaining its immutable architecture and atomic update capabilities.

The key is to follow uBlue-OS's successful patterns while adapting them to Ubuntu's package management system and Particle-OS's layer-based architecture. This ensures users can enjoy the benefits of immutable systems while still having access to the hardware support they need for gaming, development, and professional workloads.