# DKMS Implementation Plan for Particle-OS

## Overview

This document outlines the step-by-step implementation plan for adding DKMS (Dynamic Kernel Module Support) to Particle-OS, following the successful patterns established by uBlue-OS.

## Phase 1: Core DKMS Infrastructure

### 1.1 apt-layer DKMS Integration

#### Add DKMS Commands to apt-layer.sh
```bash
# New DKMS-specific commands
--dkms-status              # Show DKMS module status
--dkms-list                # List installed DKMS modules
--dkms-install <module>    # Install DKMS module
--dkms-remove <module>     # Remove DKMS module
--dkms-rebuild <module>    # Rebuild DKMS module
--dkms-rebuild-all         # Rebuild all DKMS modules
--dkms-clean <module>      # Clean DKMS build environment
--dkms-logs <module>       # Show DKMS build logs
--dkms-rollback            # Rollback failed DKMS installation
```

#### Implementation Steps:
1. **Add DKMS dependency checking** in apt-layer.sh
2. **Create DKMS layer management functions**
3. **Implement DKMS hook system**
4. **Add kernel header management**
5. **Create DKMS atomic transaction support**

### 1.2 DKMS Configuration System

#### Create DKMS Configuration Files
```bash
/usr/local/etc/particle-os/dkms/
├── dkms-settings.json     # DKMS configuration
├── kernel-versions.json   # Kernel version tracking
├── modules.json          # Installed modules list
└── hooks/                # DKMS hooks directory
    ├── pre-install.sh
    ├── post-install.sh
    ├── pre-remove.sh
    └── post-remove.sh
```

#### DKMS Settings Configuration
```json
{
  "dkms_enabled": true,
  "auto_rebuild": true,
  "build_environment": "container",
  "kernel_headers_auto": true,
  "rollback_on_failure": true,
  "log_level": "info",
  "build_timeout": 3600,
  "max_parallel_builds": 2
}
```

### 1.3 Kernel Header Management

#### Automatic Kernel Header Installation
```bash
# Function to install kernel headers
install_kernel_headers() {
    local kernel_version=$(uname -r)
    local headers_package="linux-headers-${kernel_version}"
    
    # Check if headers are installed
    if ! dpkg -l | grep -q "$headers_package"; then
        apt-layer --live-install "$headers_package"
    fi
}

# Function to verify kernel headers
verify_kernel_headers() {
    local kernel_version=$(uname -r)
    local headers_path="/usr/src/linux-headers-${kernel_version}"
    
    if [[ ! -d "$headers_path" ]]; then
        log_error "Kernel headers not found for $kernel_version"
        return 1
    fi
    
    log_success "Kernel headers verified for $kernel_version"
}
```

## Phase 2: NVIDIA Driver Support

### 2.1 NVIDIA Repository Integration

#### Add NVIDIA Repository Support
```bash
# Function to add NVIDIA repository
add_nvidia_repository() {
    local nvidia_repo="deb http://archive.ubuntu.com/ubuntu/ $(lsb_release -cs) restricted"
    
    # Add NVIDIA repository
    echo "$nvidia_repo" | sudo tee /etc/apt/sources.list.d/nvidia.list
    
    # Add NVIDIA GPG key
    wget -qO - https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/3bf863cc.pub | sudo apt-key add -
    
    # Update package lists
    apt update
}

# Function to install NVIDIA drivers
install_nvidia_drivers() {
    local driver_version="${1:-535}"
    
    # Install NVIDIA driver packages
    apt-layer --live-install \
        "nvidia-driver-${driver_version}" \
        "nvidia-settings" \
        "nvidia-prime" \
        "nvidia-modprobe"
}
```

### 2.2 NVIDIA Variant Creation

#### Create NVIDIA Gaming Variants
```bash
# Particle-OS Bazzite Gaming (NVIDIA)
create_bazzite_nvidia_variant() {
    apt-layer create-variant bazzite-gaming-nvidia \
        --base ubuntu-base/25.04 \
        --add dkms nvidia-driver-535 steam wine lutris \
        --description "Gaming variant with NVIDIA support (Ubuntu 25.04)"
}

# Particle-OS Corona Gaming (NVIDIA)
create_corona_nvidia_variant() {
    apt-layer create-variant corona-gaming-nvidia \
        --base ubuntu-base/24.04 \
        --add dkms nvidia-driver-535 kde-plasma-desktop steam wine \
        --description "KDE Plasma gaming variant with NVIDIA support (Ubuntu 24.04 LTS)"
}
```

### 2.3 NVIDIA Prime Configuration

#### NVIDIA Prime Support
```bash
# Function to configure NVIDIA Prime
configure_nvidia_prime() {
    # Create NVIDIA Prime configuration
    cat > /etc/prime/display << EOF
# NVIDIA Prime configuration
# Auto-detect GPU configuration
auto
EOF
    
    # Install NVIDIA Prime utilities
    apt-layer --live-install nvidia-prime-applet
    
    # Configure system for NVIDIA Prime
    prime-select nvidia
}

# Function to switch GPU
switch_gpu() {
    local gpu="${1:-nvidia}"
    
    case "$gpu" in
        "nvidia")
            prime-select nvidia
            log_info "Switched to NVIDIA GPU"
            ;;
        "integrated")
            prime-select intel
            log_info "Switched to integrated GPU"
            ;;
        *)
            log_error "Invalid GPU selection: $gpu"
            return 1
            ;;
    esac
}
```

## Phase 3: Advanced DKMS Features

### 3.1 Containerized DKMS Builds

#### Isolated Build Environment
```bash
# Function to create DKMS build container
create_dkms_build_container() {
    local module_name="$1"
    local kernel_version="$2"
    
    # Create build container
    cat > "/var/lib/particle-os/dkms/build-environments/${module_name}.Dockerfile" << EOF
FROM ubuntu:24.04

# Install build dependencies
RUN apt-get update && apt-get install -y \\
    build-essential \\
    dkms \\
    linux-headers-${kernel_version} \\
    git \\
    wget

# Set up DKMS environment
ENV DKMS_AUTOINSTALL=yes
ENV DKMS_BUILD_TIMEOUT=3600

WORKDIR /build
EOF
    
    # Build container
    docker build -t "dkms-${module_name}" \
        "/var/lib/particle-os/dkms/build-environments/${module_name}.Dockerfile"
}

# Function to build DKMS module in container
build_dkms_in_container() {
    local module_name="$1"
    local module_version="$2"
    local kernel_version="$3"
    
    # Run DKMS build in container
    docker run --rm \
        -v "/usr/src/${module_name}-${module_version}:/usr/src/${module_name}-${module_version}" \
        -v "/lib/modules/${kernel_version}:/lib/modules/${kernel_version}" \
        "dkms-${module_name}" \
        dkms build "${module_name}/${module_version}" -k "${kernel_version}"
}
```

### 3.2 DKMS Atomic Transactions

#### Atomic DKMS Operations
```bash
# Function for atomic DKMS installation
atomic_dkms_install() {
    local module_name="$1"
    local module_version="$2"
    
    # Create transaction
    apt-layer --begin-transaction "dkms-install-${module_name}"
    
    # Install DKMS module
    if dkms install "${module_name}/${module_version}"; then
        # Commit transaction
        apt-layer --commit-transaction "dkms-install-${module_name}"
        log_success "DKMS module ${module_name} installed successfully"
    else
        # Rollback transaction
        apt-layer --rollback-transaction "dkms-install-${module_name}"
        log_error "DKMS module ${module_name} installation failed"
        return 1
    fi
}

# Function for atomic DKMS removal
atomic_dkms_remove() {
    local module_name="$1"
    local module_version="$2"
    
    # Create transaction
    apt-layer --begin-transaction "dkms-remove-${module_name}"
    
    # Remove DKMS module
    if dkms remove "${module_name}/${module_version}"; then
        # Commit transaction
        apt-layer --commit-transaction "dkms-remove-${module_name}"
        log_success "DKMS module ${module_name} removed successfully"
    else
        # Rollback transaction
        apt-layer --rollback-transaction "dkms-remove-${module_name}"
        log_error "DKMS module ${module_name} removal failed"
        return 1
    fi
}
```

## Phase 4: Testing and Validation

### 4.1 DKMS Testing Framework

#### Create DKMS Test Suite
```bash
# Test DKMS installation
test_dkms_installation() {
    log_info "Testing DKMS installation..."
    
    # Test basic DKMS functionality
    apt-layer --dkms-install test-module
    
    # Verify installation
    if apt-layer --dkms-status | grep -q "test-module"; then
        log_success "DKMS installation test passed"
    else
        log_error "DKMS installation test failed"
        return 1
    fi
}

# Test NVIDIA driver installation
test_nvidia_installation() {
    log_info "Testing NVIDIA driver installation..."
    
    # Install NVIDIA drivers
    apt-layer --dkms-install nvidia-driver-535
    
    # Verify NVIDIA drivers
    if nvidia-smi >/dev/null 2>&1; then
        log_success "NVIDIA driver test passed"
    else
        log_error "NVIDIA driver test failed"
        return 1
    fi
}

# Test kernel update with DKMS
test_kernel_update_dkms() {
    log_info "Testing kernel update with DKMS..."
    
    # Install kernel update
    apt-layer --live-install linux-generic-hwe-24.04
    
    # Verify DKMS modules rebuilt
    if apt-layer --dkms-status | grep -q "installed"; then
        log_success "DKMS kernel update test passed"
    else
        log_error "DKMS kernel update test failed"
        return 1
    fi
}
```

### 4.2 Integration Testing

#### Full DKMS Workflow Testing
```bash
# Test complete DKMS workflow
test_dkms_workflow() {
    log_info "Testing complete DKMS workflow..."
    
    # 1. Create DKMS-enabled layer
    apt-layer ubuntu-base/24.04 dkms-test/24.04 dkms
    
    # 2. Install NVIDIA drivers
    apt-layer dkms-test/24.04 nvidia-test/24.04 nvidia-driver-535
    
    # 3. Install additional DKMS modules
    apt-layer nvidia-test/24.04 vmware-test/24.04 virtualbox-dkms
    
    # 4. Test kernel update
    apt-layer vmware-test/24.04 kernel-update-test/24.04 linux-generic-hwe-24.04
    
    # 5. Verify all modules rebuilt
    apt-layer --dkms-status
    
    log_success "DKMS workflow test completed"
}
```

## Implementation Timeline

### Week 1-2: Core Infrastructure
- [ ] Add DKMS commands to apt-layer.sh
- [ ] Create DKMS configuration system
- [ ] Implement kernel header management
- [ ] Add DKMS dependency checking

### Week 3-4: NVIDIA Support
- [ ] Add NVIDIA repository integration
- [ ] Create NVIDIA variant definitions
- [ ] Implement NVIDIA Prime support
- [ ] Add NVIDIA-specific optimizations

### Week 5-6: Advanced Features
- [ ] Implement containerized DKMS builds
- [ ] Add DKMS atomic transactions
- [ ] Create DKMS rollback mechanisms
- [ ] Add DKMS monitoring and logging

### Week 7-8: Testing and Documentation
- [ ] Create comprehensive test suite
- [ ] Test all DKMS workflows
- [ ] Update documentation
- [ ] Create user guides

## Success Criteria

### Functional Requirements
- [ ] DKMS modules can be installed and removed atomically
- [ ] NVIDIA drivers work correctly with Particle-OS
- [ ] Kernel updates automatically rebuild DKMS modules
- [ ] Failed DKMS installations can be rolled back safely
- [ ] NVIDIA Prime switching works correctly

### Performance Requirements
- [ ] DKMS builds complete within reasonable time limits
- [ ] System performance is not degraded by DKMS overhead
- [ ] NVIDIA gaming performance matches native Ubuntu
- [ ] Boot times remain acceptable with DKMS modules

### Reliability Requirements
- [ ] DKMS failures don't break the immutable system
- [ ] Rollback mechanisms work correctly
- [ ] Kernel updates don't break existing DKMS modules
- [ ] System remains stable with multiple DKMS modules

## Conclusion

This implementation plan provides a comprehensive roadmap for adding DKMS and NVIDIA support to Particle-OS. By following the successful patterns established by uBlue-OS and adapting them to Ubuntu's package management system, Particle-OS can provide the same level of hardware compatibility while maintaining its immutable architecture and atomic update capabilities.

The phased approach ensures that each component is properly tested before moving to the next phase, reducing the risk of introducing bugs or breaking the system. The comprehensive testing framework ensures that all DKMS functionality works correctly and reliably.