2025-07-14 01:09:07 -07:00

12 KiB

Raw Blame History

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

# 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:

Add DKMS dependency checking in apt-layer.sh
Create DKMS layer management functions
Implement DKMS hook system
Add kernel header management
Create DKMS atomic transaction support

1.2 DKMS Configuration System

Create DKMS Configuration Files

/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

{
  "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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.

12 KiB Raw Blame History