Skip to content

kernel.md

Latest commit

 

History

History
156 lines (106 loc) · 4.05 KB

kernel.md

File metadata and controls

156 lines (106 loc) · 4.05 KB

Kernel Configuration

This guide explains how the kernel build works and how to customize it.

Overview

mvirt-one uses a minimal Linux kernel optimized for virtualization. The kernel configuration uses a fragment-based approach rather than a full .config file.

Config Fragment Approach

Instead of maintaining a full kernel config (~8000+ lines), we use a small fragment (kernel.config, ~200 lines) that contains only our customizations.

Build process:

  1. make tinyconfig - Start with the smallest possible kernel
  2. merge_config.sh - Merge our fragment on top
  3. make olddefconfig - Fill in remaining options with defaults

Benefits:

  • Easy to see what options we actually need
  • Survives kernel upgrades better
  • Clear documentation of requirements

Current Configuration

The mvirt-one/kernel.config fragment includes:

Category Options
Virtio virtio-blk, virtio-net, virtio-console, virtio-vsock
Filesystems ext4, tmpfs, proc, sysfs, devtmpfs
Networking IPv4, IPv6, Unix sockets
Serial 8250 UART for console

The kernel is optimized for MicroVMs - no hardware drivers needed.

Customizing the Kernel

Finding Options with menuconfig

# Download and extract kernel source (if not already done)
make os-download

# Open interactive config menu
make menuconfig

Navigate the menus to find the option you need. Press / to search by name.

Testing Changes

Changes made in menuconfig are saved to .config and can be tested immediately:

make menuconfig    # Enable option, save to .config
make kernel        # Build kernel
make iso           # Build ISO for testing

Making Changes Permanent

If the option works, add it to the fragment:

# Add to kernel.config
echo "CONFIG_MY_DRIVER=y" >> mvirt-one/kernel.config

Or edit mvirt-one/kernel.config directly.

Important: Changes only in .config are lost after make clean or when kernel.config is modified, because .config is regenerated from the fragment.

Disabling Options

To explicitly disable an option:

# In kernel.config
# CONFIG_WIRELESS is not set

Adding Hardware Support

Adding a Network Driver

  1. Find the driver name (e.g., from lspci -k on target hardware)
  2. Search in menuconfig: / then search for driver name
  3. Note the config option (e.g., CONFIG_IXGBE)
  4. Add to kernel.config: 
    # Intel 10GbE (ixgbe)
CONFIG_IXGBE=y

Adding a Storage Controller

Same process - find the driver, add the config option:

# Example: Add support for specific RAID controller
CONFIG_MEGARAID_SAS=y

Checking Dependencies

Some drivers have dependencies. menuconfig shows these - look for options marked with --- or [*] that appear when you enable something.

Common dependencies to check:

  • CONFIG_PCI=y - Required for most hardware
  • CONFIG_SCSI=y - Required for storage drivers
  • CONFIG_PHYLIB=y - Required for some network drivers

Kernel Version

The kernel version is specified in mvirt-one/kernel.version:

cat mvirt-one/kernel.version

To update the kernel:

  1. Edit kernel.version with new version number
  2. Run make distclean to remove old source
  3. Run make os to download and build new version
  4. Test thoroughly - config options may have changed

Troubleshooting

Option Not Taking Effect

Check if the option has unmet dependencies:

cd mvirt-one/kernel
./scripts/config --state CONFIG_MY_OPTION

Kernel Too Large

Review enabled options. Common space savings:

  • Disable unused network drivers
  • Disable debug options (CONFIG_DEBUG_*)
  • Disable unused filesystems

Boot Fails

Ensure these core options are enabled:

  • CONFIG_BLK_DEV_INITRD=y - Initramfs support
  • CONFIG_RD_GZIP=y - Gzip decompression
  • CONFIG_DEVTMPFS=y - Device filesystem
  • CONFIG_TTY=y - Terminal support

Reference