Disclaimer:
This guide is not for the faint of heart! It assumes that you have some idea of what a statically linked kernel is, and how to build one for your hardware in a source-based distribution.
Also you can use any suitable kernel for your hardware that:
This guide assumes that the IX package manager is in your PATH:
ix# export PATH=/mnt/ix/home/ix/ix:${PATH} # assumes we are in stal/IX installer, before reboot
ix# export PATH=/home/ix/ix:${PATH} # assumes we are in stal/IX installer, after reboot
ix# export PATH=/your/local/checkout:${PATH} # assumes local ix checkout per user
ix# ix list
The goal of this guide is to build a kernel that contains all the components needed to run it.
First, you need to know the list of modules that your hardware supports.
To do this, you can download any regular distribution with a working automatic hardware detection system.
You need to do the following:
ubuntu# lspci -k
03:00.0 Class 0300: 1002:1638 amdgpu
02:00.0 Class 0108: 144d:a809 nvme
03:00.7 Class 1180: 1022:15e4 pcie_mp2_amd
03:00.5 Class 0480: 1022:15e2 snd_rn_pci_acp3x
01:00.0 Class 0280: 8086:2723 iwlwifi
03:00.3 Class 0c03: 1022:1639 xhci_hcd
03:00.1 Class 0403: 1002:1637 snd_hda_intel
00:08.1 Class 0604: 1022:1635 pcieport
00:02.4 Class 0604: 1022:1634 pcieport
03:00.6 Class 0403: 1022:15e3 snd_hda_intel
00:02.2 Class 0604: 1022:1634 pcieport
03:00.4 Class 0c03: 1022:1639 xhci_hcd
03:00.2 Class 1080: 1022:15df ccp
00:14.0 Class 0c05: 1022:790b piix4_smbus
00:08.2 Class 0604: 1022:1635 pcieport
...
In some distributions, you may need to run lspci -k | grep Kernel.
The last column is a list of modules we need. Write them down.
Next, we need to prepare a directory with the kernel sources for which we are building a config. Let’s say we want to use kernel 6.15:
ix# mkdir kernel
ix# cd kernel
# get current linux kernel source
ix# wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-$(grep 6.15 $(dirname $(which ix))/pkgs/bin/kernel/6/15/ver.sh).tar.xz
ix# tar xf linux-6.15.3.tar.xz
ix# cd linux-6.15.3
Let’s copy the old kernel configuration into our tree:
ix# cp $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_14 ./.config
Run the kernel configurator:
ix run set/menuconfig -- make HOSTCC=cc CC=cc LD=ld.lld menuconfig
You need to find all the modules from the list above in the configurator (there is a search!) and add them to the configuration.
That being said:
dmesg | grep firmware on a running system to get information about the missing firmware!Alternatively, you can combine the previous commands into one:
...
ix# cd linux-6.15.3
ix# ix tool reconf $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_14
Most often, to understand what needs to be included in the kernel configuration for a particular device operation, it is useful to search the web for the module name and the Gentoo/Arch link, as they have the largest knowledge base on the topic:
After configuring the kernel, copy the modified configuration to the base:
ix# cp .config $(dirname $(which ix))/pkgs/bin/kernel/configs/cfg_6_14
After that, you can add the kernel to the system realm in the usual way:
ix# ix mut system bin/kernel/6/15
ix# ls /bin/kernel-*
/bin/kernel-6-15
Remember that path, you will need it later in GRUB CLI or in grub.cfg.
Alternatively, you can use a separate realm for the bootstrap kernel:
ix# ix mut kernel bin/kernel/6/15
ix# ls /ix/realm/kernel/bin/kernel-*
/ix/realm/kernel/bin/kernel-6-15
Remember that path, you will need it later in GRUB CLI or in grub.cfg.
In legacy BIOS, the kernel needs to have the byte sequence aa55 at offset 510 in order for it to be bootable by GRUB. You can verify this using hexdump -s 510 /bin/kernel-* | head -n 1; if the output doesn’t start with 00001fe aa55, then it is not bootable and you will get error: invalid magic number. in GRUB. In that case, rebuild the kernel with CONFIG_EFI_STUB=n.