nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml
Matthieu Coudron eb7e0d42db doc: Explain how to hack on kernel
Presents the options available (linuxManualConfig versus overriding
extraConfig, ignoreConfigErrors, autoModules, kernelPreferBuiltin.

For advanced hostPlatform customization refer to the commands shared by ericson1234 at
https://github.com/NixOS/nixpkgs/pull/33813 but it is too advanced to
put in the doc.
2018-06-08 10:36:21 +03:00

139 lines
4.9 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-kernel-config">
<title>Linux Kernel</title>
<para>
You can override the Linux kernel and associated packages using the option
<option>boot.kernelPackages</option>. For instance, this selects the Linux
3.10 kernel:
<programlisting>
<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;
</programlisting>
Note that this not only replaces the kernel, but also packages that are
specific to the kernel version, such as the NVIDIA video drivers. This
ensures that driver packages are consistent with the kernel.
</para>
<para>
The default Linux kernel configuration should be fine for most users. You can
see the configuration of your current kernel with the following command:
<programlisting>
zcat /proc/config.gz
</programlisting>
If you want to change the kernel configuration, you can use the
<option>packageOverrides</option> feature (see
<xref
linkend="sec-customising-packages" />). For instance, to enable support
for the kernel debugger KGDB:
<programlisting>
nixpkgs.config.packageOverrides = pkgs:
{ linux_3_4 = pkgs.linux_3_4.override {
extraConfig =
''
KGDB y
'';
};
};
</programlisting>
<varname>extraConfig</varname> takes a list of Linux kernel configuration
options, one per line. The name of the option should not include the prefix
<literal>CONFIG_</literal>. The option value is typically
<literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build
something as a kernel module).
</para>
<para>
Kernel modules for hardware devices are generally loaded automatically by
<command>udev</command>. You can force a module to be loaded via
<xref linkend="opt-boot.kernelModules"/>, e.g.
<programlisting>
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
</programlisting>
If the module is required early during the boot (e.g. to mount the root file
system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:
<programlisting>
<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];
</programlisting>
This causes the specified modules and their dependencies to be added to the
initial ramdisk.
</para>
<para>
Kernel runtime parameters can be set through
<xref linkend="opt-boot.kernel.sysctl"/>, e.g.
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
</programlisting>
sets the kernels TCP keepalive time to 120 seconds. To see the available
parameters, run <command>sysctl -a</command>.
</para>
<section>
<title>Customize your kernel</title>
<para>
The first step before compiling the kernel is to generate an appropriate
<literal>.config</literal> configuration. Either you pass your own config via
the <literal>configfile</literal> setting of <literal>linuxManualConfig</literal>:
<screen><![CDATA[
custom-kernel = super.linuxManualConfig {
inherit (super) stdenv hostPlatform;
inherit (linux_4_9) src;
version = "${linux_4_9.version}-custom";
configfile = /home/me/my_kernel_config;
allowImportFromDerivation = true;
};
]]></screen>
You can edit the config with this snippet (by default <command>make menuconfig</command> won't work
out of the box on nixos):
<screen><![CDATA[
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})'
]]></screen>
or you can let nixpkgs generate the configuration.
Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>.
The answers depend on parameters passed to <filename>pkgs/os-specific/linux/kernel/generic.nix</filename>
(which you can influence by overriding <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
<screen><![CDATA[
mptcp93.override ({
name="mptcp-local";
ignoreConfigErrors = true;
autoModules = false;
kernelPreferBuiltin = true;
enableParallelBuilding = true;
extraConfig = ''
DEBUG_KERNEL y
FRAME_POINTER y
KGDB y
KGDB_SERIAL_CONSOLE y
DEBUG_INFO y
'';
});
]]></screen>
</para>
</section>
<section>
<title>Developing kernel modules</title>
<para>
When developing kernel modules it's often convenient to run edit-compile-run
loop as quickly as possible. See below snippet as an example of developing
<literal>mellanox</literal> drivers.
</para>
<screen><![CDATA[
$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
$ unpackPhase
$ cd linux-*
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
]]></screen>
</section>
</chapter>