# Debian Kernel Packages - Intel Distribution

Complete guide to Debian packages generated by the Intel kernel build system.

For project overview and Intel overlay system, see [Main README](../README.md).

---

## Quick Reference

### Package Categories

| Category | Packages | Purpose |
|----------|----------|---------|
| **Core** | 6 per variant | Required for boot (base, binary, modules, image) |
| **Development** | 3 | Building external modules (headers, kbuild, bpf-dev) |
| **Debug** | 2 per variant | Crash analysis (debug symbols ~1.3GB each) |
| **Performance** | 3 | Profiling and tracing (perf, bpftool, rtla) |
| **Utilities** | 7 | Power management, thermal monitoring, profiling, USB/IP |

### Kernel Variants

- **Standard** (`-amd64`): General purpose, desktop, server
- **Real-Time** (`-rt-amd64`): Low-latency, PREEMPT_RT, industrial control
  - **Auto-configures boot parameters**: RT kernel packages automatically apply optimized boot parameters to `/etc/default/grub` during installation
  - See [RT Kernel Parameters](../docs/RT-KERNEL-PARAMETERS.md) for details

---

## Core Kernel Packages (Required)

### Installation Order

Must install in this exact order:

```bash
1. linux-base-<VERSION>-<VARIANT>      # Base scripts (~140K)
2. linux-base-<VARIANT>                # Base meta-package (~1K)
3. linux-binary-<VERSION>-<VARIANT>    # Kernel vmlinuz (~15M)
4. linux-modules-<VERSION>-<VARIANT>   # .ko modules (~85M)
5. linux-image-<VERSION>-<VARIANT>     # Image package (~2K)
6. linux-image-<VARIANT>               # Image meta-package (~1.5K)
```

### Package Details

| Package | Contents | Critical Notes |
|---------|----------|----------------|
| `linux-base-*` | Configuration, maintenance scripts, hooks | Required dependency for all |
| `linux-binary-*` | `/boot/vmlinuz-*`, `System.map` | The bootable kernel image |
| `linux-modules-*` | `/lib/modules/<VERSION>/` with all .ko files | **Module directory must match `uname -r`** |
| `linux-image-*` | Meta, triggers initramfs + GRUB update | Coordinates installation; **RT variant auto-applies boot parameters** |

**Critical**: Module directory name must exactly match kernel version string or `modprobe` will fail to find modules.

**RT Kernel Note**: When installing `linux-image-*-rt-amd64`, the package automatically:
- Reads RT boot parameters from `/usr/share/doc/linux-image-VERSION/kernel-rt-parameter`
- Backs up `/etc/default/grub` to `/etc/default/grub.pre-rt`
- Adds RT parameters to `GRUB_CMDLINE_LINUX_DEFAULT`
- Runs `update-grub`
- See [RT Kernel Parameters Guide](../docs/RT-KERNEL-PARAMETERS.md) for details

---

## Development Packages

For building external modules (DKMS, custom drivers):

```bash
# After installing core kernel
sudo dpkg -i linux-headers-<VERSION>-<VARIANT>_*.deb
sudo dpkg -i linux-kbuild-<VERSION>_*.deb
```

| Package | Size | Purpose |
|---------|------|---------|
| `linux-headers-*` | ~2M | Kernel headers, Module.symvers, .config |
| `linux-kbuild-*` | ~1M | Build scripts and Makefiles |
| `linux-bpf-dev` | ~600K | BPF/eBPF development headers |

**Usage**:
```bash
cd /path/to/module
make -C /lib/modules/$(uname -r)/build M=$(pwd) modules
```

---

## Debug Packages

For kernel crash analysis:

| Package | Size | Purpose |
|---------|------|---------|
| `linux-image-*-dbg` | ~1.3GB | Uncompressed vmlinux with DWARF symbols |

**Only install when actively debugging**. Very large files.

```bash
# Analyze crash dump
crash /usr/lib/debug/boot/vmlinux-<VERSION> /var/crash/vmcore
```

---

## Performance Tools

| Package | Tool | Purpose |
|---------|------|---------|
| `linux-perf` | `perf` | CPU profiling, tracing, PMU access |
| `bpftool` | `bpftool` | Inspect/manipulate eBPF programs |
| `rtla` | `rtla` | RT latency analysis (RT kernel only) |

**Examples**:
```bash
perf top                    # Live CPU profiling
perf record -g -a           # Record call stacks
bpftool prog list           # List BPF programs
rtla osnoise top            # RT noise monitoring
```

---

## System Utilities

| Package | Tools | Purpose |
|---------|-------|---------|
| `libcpupower1` | Library only | Runtime library for cpupower (required dependency) |
| `linux-cpupower` | `cpupower`, `turbostat`, `x86_energy_perf_policy`, `intel-speed-select` | CPU frequency/power management and monitoring |
| `linux-perf` | `perf` | CPU profiling, tracing, PMU access, flamegraphs |
| `linux-misc-tools` | `tmon`, `thermometer`, `bootconfig`, `ihex2fw` | Thermal monitoring and misc utilities |
| `hyperv-daemons` | KVP, VSS, FCOPY | Hyper-V integration services |
| `intel-sdsi` | `intel-sdsi` | Intel Software Defined Silicon management |
| `usbip` | `usbip` | USB over IP |

---

## Installation Scenarios

### Scenario 1: Minimal Runtime (~100MB)

Production server, minimal footprint:

```bash
cd build/packages/deb/
sudo dpkg -i \
  linux-base-*-amd64_*.deb \
  linux-base-amd64_*.deb \
  linux-binary-*-amd64_*.deb \
  linux-modules-*-amd64_*.deb \
  linux-image-*-amd64_*.deb \
  linux-image-amd64_*.deb
sudo apt-get install -f
sudo update-grub
sudo reboot
```

### Scenario 2: Development System (~104MB)

Add module building capability:

```bash
# After Scenario 1
sudo dpkg -i linux-headers-*-amd64_*.deb linux-kbuild-*_*.deb
```

### Scenario 3: Tools Only (~3MB)

System utilities without kernel packages (use when kernel is already installed):

```bash
# Install tools with force-overwrite if conflicts with system packages
sudo dpkg --force-overwrite -i \
  libcpupower1_*.deb \
  linux-cpupower_*.deb \
  linux-perf_*.deb \
  linux-misc-tools_*.deb \
  hyperv-daemons_*.deb \
  intel-sdsi_*.deb \
  usbip_*.deb
```

**Tools included:**
- `cpupower`, `turbostat`, `x86_energy_perf_policy`, `intel-speed-select` (CPU power/freq management)
- `perf` (profiling and tracing)
- `tmon`, `thermometer` (thermal monitoring)
- `bootconfig`, `ihex2fw` (boot and firmware utilities)
- Hyper-V integration services
- Intel SDSi management
- USB over IP

**Note:** May conflict with `linux-tools-common`. Use `--force-overwrite` to replace system tools with kernel-specific versions.

### Scenario 4: Real-Time System (~100MB)

Replace `-amd64` with `-rt-amd64` in all package names:

```bash
sudo dpkg -i \
  linux-base-*-rt-amd64_*.deb \
  linux-base-rt-amd64_*.deb \
  linux-binary-*-rt-amd64_*.deb \
  linux-modules-*-rt-amd64_*.deb \
  linux-image-*-rt-amd64_*.deb \
  linux-image-rt-amd64_*.deb
sudo apt-get install -f
sudo reboot
```

**RT Kernel Auto-Configuration:**

When installing `linux-image-*-rt-amd64`, the package automatically:
1. Reads RT boot parameters from `intel/kernel-rt-parameter`
2. Backs up `/etc/default/grub` to `/etc/default/grub.pre-rt` (first time only)
3. Adds RT-optimized parameters to `GRUB_CMDLINE_LINUX_DEFAULT`
4. Runs `update-grub` to update bootloader configuration
5. Notifies that a reboot is required

**RT Parameters include:**
- CPU isolation (`isolcpus`, `nohz_full`, `rcu_nocbs`)
- Power management optimization (`intel_pstate=disable`, `idle=poll`)
- Graphics configuration (`i915.enable_guc`, `i915.max_vfs`)
- Clock source (`clocksource=tsc`, `tsc=reliable`)
- IOMMU settings (`intel_iommu=on`, `iommu=pt`)
- And many more for RT performance

**Manual verification:**
```bash
# View applied parameters
cat /proc/cmdline

# View original backup
cat /etc/default/grub.pre-rt
```

See [RT Kernel Parameters Documentation](../docs/RT-KERNEL-PARAMETERS.md) for complete details.

### Scenario 5: Kernel Debugging (~1.4GB)

Add debug symbols:

```bash
# After Scenario 1
sudo dpkg -i linux-image-*-amd64-dbg_*.deb
```

---

## Package Types

### Version-Specific Packages

Example: `linux-binary-6.18.20-intel+260417t093242z-amd64_6.18.20-intel+260417t093242z_amd64.deb`

- Contains actual files
- Tied to specific kernel version
- Multiple versions can coexist

### Meta-Packages

Example: `linux-image-amd64_6.18.20-intel+260417t093242z_amd64.deb`

- Size: 1-2KB
- Only contains dependency on latest version-specific package
- Enables automatic upgrades:
  ```bash
  sudo apt install linux-image-amd64
  # Later...
  sudo apt upgrade linux-image-amd64  # Pulls new version
  ```

---

## Troubleshooting

### "modprobe: FATAL: Module not found"

**Cause**: Kernel version mismatch between binary and modules.

**Prevention**:
```bash
scripts/verify-kernel-package.sh linux-binary-*.deb linux-modules-*.deb
```

**Check**:
```bash
uname -r                      # Kernel version
ls /lib/modules/              # Module directory name (must match)
```

### Package installation fails

```bash
# Fix dependencies
sudo apt-get install -f

# Or install in correct order (see Installation Order section)
```

### Cannot build external modules

```bash
# Install headers
sudo dpkg -i linux-headers-$(uname -r)_*.deb
```

### GRUB doesn't show new kernel

```bash
sudo update-grub
grep menuentry /boot/grub/grub.cfg | grep $(uname -r)
```

### Kernel panic or boot failure

1. Reboot, select previous kernel from GRUB
2. Check logs:
   ```bash
   journalctl -b -1          # Previous boot
   dmesg | less
   ```
3. Verify packages:
   ```bash
   dpkg -l | grep linux-image
   ```

---

## Package Management

### Listing Kernels

```bash
dpkg -l | grep linux-image              # Installed packages
uname -r                                # Current kernel
grep menuentry /boot/grub/grub.cfg     # Boot entries
```

### Removing Old Kernels

```bash
# Remove specific version
sudo apt-get remove linux-image-VERSION-amd64 linux-headers-VERSION-amd64

# Remove unused kernels (keeps current + one previous)
sudo apt-get autoremove

# Update GRUB
sudo update-grub
```

### Inspecting Packages

```bash
dpkg -c package.deb           # List contents
dpkg -I package.deb           # Show metadata
dpkg -L package-name          # List installed files
```

---

## Storage Requirements

| Type | Size | Packages |
|------|------|----------|
| Minimal runtime | 100 MB | 6 core |
| + Development | 104 MB | + headers + kbuild |
| Tools only | 3 MB | 7 tool packages (no kernel) |
| + Debug | 1.4 GB | + debug symbols |
| + All tools | 1.5 GB | + perf, bpf, cpupower, etc. |
| Complete build | 2.8 GB | All 30+ packages (both variants) |

---

## Standard vs RT Kernel

| Aspect | Standard | Real-Time |
|--------|----------|-----------|
| Latency | ~100μs - 1ms | <50μs (can achieve <10μs) |
| Throughput | Higher | 5-10% lower |
| Preemption | Voluntary | Full (PREEMPT_RT) |
| Use case | General purpose | Deterministic timing |
| Boot parameters | Manual configuration | **Auto-configured on install** |
| GRUB backup | Not applicable | Automatic (`/etc/default/grub.pre-rt`) |

**Choose RT for**: Robotics, industrial control, CNC, pro audio, financial trading

**Choose Standard for**: Desktop, server, general computing

### RT Kernel Features

The RT kernel packages include automatic boot parameter configuration:
- **CPU isolation**: Dedicated CPU cores for RT tasks
- **Power management**: Disabled C-states and frequency scaling for predictable performance
- **Interrupt handling**: Thread all interrupts, configure IRQ affinity
- **Clock source**: TSC as reliable clock source
- **Graphics optimization**: GPU configuration for low-latency operation

See [RT Kernel Parameters](../docs/RT-KERNEL-PARAMETERS.md) for the complete list of automatically applied parameters and customization options.

---

## Best Practices

1. ✅ Verify packages before deployment (`verify-kernel-package.sh`)
2. ✅ Install in correct order (base → binary → modules → image)
3. ✅ Test in staging before production
4. ✅ Keep old kernel for fallback
5. ⚠️ Only install debug packages when needed (1.3GB each)
6. ⚠️ Monitor disk space with multiple kernel versions

---

## Related Documentation

- **[Main README](../README.md)** - Project overview, Intel overlay system
- **[Module Packaging](MODULE_PACKAGING.md)** - Standalone module packages
- **[RPM Packages](../rpm/README.md)** - RPM build system
- **[Intel Overlay](../intel/README.md)** - Shared patches and configs
- **[RT Kernel Parameters](../docs/RT-KERNEL-PARAMETERS.md)** - RT kernel auto-configuration
- **[RT Package Structure](../docs/RT-PACKAGE-STRUCTURE.md)** - RT kernel package details
- **[DKMS Packages](../dkms/README.md)** - Dynamic kernel module packages

---

**Version**: 1.1  
**Updated**: 2026-05-19  
**For**: Intel kernel Debian packages
