robojerk/particle-os-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
particle-os-tools/src/akmods-apt/dkms-integration.md
robojerk 29b9675689
Some checks failed
Compile apt-layer / compile (push) Failing after 2s
Details
fixed paths, created ci/cd workflow
2025-07-14 14:22:06 -07:00

10 KiB
Raw Blame History

AKMODS and DKMS Integration Architecture

Overview

This document clarifies the role of DKMS in the AKMODS architecture, addressing the relationship between AKMODS (which creates pre-built packages) and DKMS (which builds modules on-demand).

AKMODS vs DKMS: Complementary Approaches

AKMODS Approach (Primary)

  • Pre-built Packages: AKMODS creates fully compiled .deb packages with kernel modules
  • OCI Distribution: Packages are distributed via container registry
  • Atomic Installation: Direct installation via dpkg with atomic operations
  • No Runtime Compilation: Modules are pre-compiled and ready to use

DKMS Approach (Fallback)

  • On-demand Building: DKMS builds modules when needed on the target system
  • Source Distribution: Distributes source code and build instructions
  • Runtime Compilation: Compiles modules against the running kernel
  • Traditional Method: Standard approach for kernel modules

AKMODS Architecture Clarification

Build-Time DKMS Usage

# AKMODS build container uses DKMS for compilation
FROM ubuntu:24.04

# Install build dependencies including DKMS
RUN apt-get update && apt-get install -y \
    build-essential \
    linux-headers-generic \
    dkms \                    # ← DKMS used during build
    debhelper \
    dh-dkms \                 # ← DKMS packaging tools
    kernel-package \
    fakeroot

# AKMODS uses DKMS to compile modules in container
akmods-apt-daemon build-nvidia-akmods nvidia-driver-535 6.8.0-25-generic
├── 1. Extract .run file contents
├── 2. Apply kernel compatibility patches
├── 3. Use DKMS to compile modules    # ← DKMS used here
├── 4. Extract compiled .ko files
├── 5. Create DEB package
└── 6. Upload to registry

Runtime Package Structure

# Final AKMODS package (NO DKMS runtime dependency)
kmod-nvidia-535-6.8.0-25-generic_535.154.05-1_amd64.deb
├── control.tar.gz
│   ├── control              # Package metadata
│   ├── postinst            # Post-installation script
│   └── prerm               # Pre-removal script
├── data.tar.gz
│   └── lib/modules/6.8.0-25-generic/extra/
│       ├── nvidia.ko       # ← Pre-compiled kernel module
│       ├── nvidia-modeset.ko
│       ├── nvidia-drm.ko
│       ├── nvidia-uvm.ko
│       └── nvidia-peermem.ko
└── debian-binary

Corrected debian/control

# Corrected debian/control (removed DKMS runtime dependency)
Package: kmod-nvidia-535
Version: 535.154.05-1
Architecture: amd64
Depends: 
  linux-headers-generic,    # ← For module loading verification
  nvidia-settings,          # ← User-space utilities
  nvidia-prime              # ← GPU switching support
# Removed: dkms (not needed at runtime)
Description: NVIDIA proprietary drivers (535.154.05)
  Pre-compiled kernel modules for NVIDIA graphics drivers version 535.154.05.
  Supports RTX 40/30 series and compatible hardware.

AKMODS Build Process with DKMS

Step 1: DKMS Source Package Creation

# AKMODS creates DKMS-compatible source structure
akmods-apt-daemon create-dkms-source nvidia-driver-535 535.154.05
├── 1. Extract .run file contents
├── 2. Create DKMS source structure
│   ├── /usr/src/nvidia-driver-535-535.154.05/
│   │   ├── dkms.conf
│   │   ├── Makefile
│   │   ├── nvidia.c
│   │   ├── nvidia-modeset.c
│   │   └── ...
│   └── Apply kernel compatibility patches
└── 3. Prepare for DKMS compilation

Step 2: DKMS Compilation in Container

# AKMODS uses DKMS to compile modules
akmods-apt-daemon compile-with-dkms nvidia-driver-535 6.8.0-25-generic
├── 1. Set up DKMS environment
│   ├── Install kernel headers
│   ├── Configure DKMS
│   └── Set up build environment
├── 2. DKMS compilation
│   ├── dkms add nvidia-driver-535/535.154.05
│   ├── dkms build nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
│   └── dkms install nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
├── 3. Extract compiled modules
│   ├── Copy .ko files from DKMS build directory
│   ├── Verify module compilation
│   └── Generate module metadata
└── 4. Clean up DKMS environment
    ├── dkms remove nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
    └── Clean build artifacts

Step 3: Package Creation (No DKMS)

# AKMODS creates DEB package without DKMS dependency
akmods-apt-daemon create-deb-package nvidia-driver-535
├── 1. Create DEB package structure
│   ├── Package compiled .ko files
│   ├── Add post-installation scripts
│   ├── Generate package metadata
│   └── Create package manifest
├── 2. Add installation scripts
│   ├── postinst: Load modules, update initramfs
│   ├── prerm: Unload modules, cleanup
│   └── triggers: Handle kernel updates
└── 3. Final package
    ├── kmod-nvidia-535-6.8.0-25-generic_535.154.05-1_amd64.deb
    └── Ready for distribution

AKMODS vs DKMS: When to Use Each

AKMODS (Recommended)

# Use AKMODS for:
# - Pre-built, tested packages
# - Fast installation
# - Atomic operations
# - Immutable system compatibility

apt-layer --akmods-install nvidia-driver-535
├── Download pre-built package from registry
├── Install via dpkg
├── Load kernel modules
└── Configure system

DKMS (Fallback)

# Use DKMS for:
# - Custom kernel modules
# - Experimental drivers
# - Hardware not supported by AKMODS
# - Development and testing

apt-layer --dkms-install custom-module
├── Install DKMS source package
├── Build module on target system
├── Install compiled module
└── Configure module loading

Hybrid Approach: AKMODS with DKMS Fallback

Primary: AKMODS Pre-built Packages

# AKMODS primary workflow
akmods-apt-daemon install-nvidia nvidia-driver-535
├── 1. Check for pre-built package
│   ├── Query OCI registry
│   ├── Check kernel compatibility
│   └── Verify package availability
├── 2. Install pre-built package
│   ├── Download kmod-nvidia-535 package
│   ├── Install via dpkg
│   ├── Load kernel modules
│   └── Configure system
└── 3. Verify installation
    ├── Test module loading
    ├── Verify GPU functionality
    └── Log success

Fallback: DKMS On-demand Building

# DKMS fallback when no pre-built package available
akmods-apt-daemon install-nvidia-fallback nvidia-driver-535
├── 1. Check for pre-built package (failed)
├── 2. Fall back to DKMS
│   ├── Install nvidia-driver-535-dkms package
│   ├── Build module with DKMS
│   ├── Install compiled module
│   └── Configure system
├── 3. Create AKMODS package for future use
│   ├── Extract compiled modules
│   ├── Create DEB package
│   ├── Upload to registry
│   └── Update package index
└── 4. Verify installation
    ├── Test module loading
    ├── Verify GPU functionality
    └── Log success

AKMODS Configuration for DKMS Integration

AKMODS Configuration

# akmods.yaml with DKMS integration
module: nvidia-driver-535
version: "535.154.05"
description: "NVIDIA proprietary drivers (RTX 40/30 series)"

build:
  method: "dkms"              # ← Use DKMS for compilation
  dependencies:
    - "build-essential"
    - "linux-headers-generic"
    - "dkms"                  # ← Build-time dependency
    - "fakeroot"
    - "debhelper"
  
  dkms_config:
    enabled: true
    source_structure: "nvidia-run"
    patch_method: "kernel-compatibility"
    build_timeout: 3600
  
  runtime_dependencies:       # ← Runtime dependencies (no DKMS)
    - "linux-headers-generic"
    - "nvidia-settings"
    - "nvidia-prime"

distribution:
  method: "pre-built-deb"     # ← Distribute as pre-built package
  registry: "registry.particle-os.org/akmods"
  fallback: "dkms"            # ← Fallback to DKMS if needed

DKMS Configuration File

# dkms.conf for AKMODS build process
PACKAGE_NAME="nvidia-driver-535"
PACKAGE_VERSION="535.154.05"
BUILT_MODULE_NAME[0]="nvidia"
BUILT_MODULE_NAME[1]="nvidia-modeset"
BUILT_MODULE_NAME[2]="nvidia-drm"
BUILT_MODULE_NAME[3]="nvidia-uvm"
BUILT_MODULE_NAME[4]="nvidia-peermem"

DEST_MODULE_LOCATION[0]="/kernel/drivers/video"
DEST_MODULE_LOCATION[1]="/kernel/drivers/video"
DEST_MODULE_LOCATION[2]="/kernel/drivers/gpu/drm"
DEST_MODULE_LOCATION[3]="/kernel/drivers/gpu"
DEST_MODULE_LOCATION[4]="/kernel/drivers/gpu"

AUTOINSTALL="yes"
MAKE[0]="make -C ${kernel_source_dir} M=${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build modules"
CLEAN="make -C ${kernel_source_dir} M=${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build clean"

Benefits of This Architecture

1. Best of Both Worlds

  • AKMODS: Fast, reliable, pre-built packages
  • DKMS: Flexible, on-demand building when needed

2. Reduced Complexity

  • Build-time: Use DKMS for reliable compilation
  • Runtime: Simple package installation without DKMS overhead

3. Fallback Safety

  • Primary: AKMODS pre-built packages
  • Fallback: DKMS when pre-built packages unavailable

4. Community Compatibility

  • Leverage: Existing DKMS infrastructure and expertise
  • Extend: With AKMODS pre-built distribution

Conclusion

The AKMODS architecture uses DKMS as a build-time tool for reliable kernel module compilation, but distributes pre-built packages that don't require DKMS at runtime. This approach:

  1. Leverages DKMS expertise for compilation
  2. Eliminates runtime DKMS dependency for faster installation
  3. Provides fallback mechanisms when pre-built packages aren't available
  4. Maintains compatibility with existing DKMS workflows

This clarification resolves the ambiguity identified by the reviewer and provides a clear, practical architecture that combines the strengths of both approaches.