diff options
| -rw-r--r-- | nixos/doc/manual/configuration/configuration.xml | 2 | ||||
| -rw-r--r-- | nixos/doc/manual/configuration/linux-kernel.chapter.md | 135 | ||||
| -rw-r--r-- | nixos/doc/manual/configuration/linux-kernel.xml | 138 | ||||
| -rw-r--r-- | nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml | 153 |
4 files changed, 289 insertions, 139 deletions
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index cd56ac774d0..56574680f9c 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -22,7 +22,7 @@ <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" /> <xi:include href="../from_md/configuration/xfce.chapter.xml" /> <xi:include href="networking.xml" /> - <xi:include href="linux-kernel.xml" /> + <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" /> <xi:include href="subversion.xml" /> <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> <xi:include href="profiles.xml" /> diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md new file mode 100644 index 00000000000..95af1666389 --- /dev/null +++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md @@ -0,0 +1,135 @@ +# Linux Kernel {#sec-kernel-config} + +You can override the Linux kernel and associated packages using the +option `boot.kernelPackages`. For instance, this selects the Linux 3.10 +kernel: + +```nix +boot.kernelPackages = pkgs.linuxPackages_3_10; +``` + +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. + +The default Linux kernel configuration should be fine for most users. +You can see the configuration of your current kernel with the following +command: + +```ShellSession +zcat /proc/config.gz +``` + +If you want to change the kernel configuration, you can use the +`packageOverrides` feature (see [](#sec-customising-packages)). For +instance, to enable support for the kernel debugger KGDB: + +```nix +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; +``` + +`extraConfig` takes a list of Linux kernel configuration options, one +per line. The name of the option should not include the prefix +`CONFIG_`. The option value is typically `y`, `n` or `m` (to build +something as a kernel module). + +Kernel modules for hardware devices are generally loaded automatically +by `udev`. You can force a module to be loaded via +[`boot.kernelModules`](options.html#opt-boot.kernelModules), e.g. + +```nix +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +``` + +If the module is required early during the boot (e.g. to mount the root +file system), you can use [`boot.initrd.kernelModules`](options.html#opt-boot.initrd.kernelModules): + +```nix +boot.initrd.kernelModules = [ "cifs" ]; +``` + +This causes the specified modules and their dependencies to be added to +the initial ramdisk. + +Kernel runtime parameters can be set through +[`boot.kernel.sysctl`](options.html#opt-boot.kernel.sysctl), e.g. + +```nix +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; +``` + +sets the kernel's TCP keepalive time to 120 seconds. To see the +available parameters, run `sysctl -a`. + +## Customize your kernel {#sec-linux-config-customizing} + +The first step before compiling the kernel is to generate an appropriate +`.config` configuration. Either you pass your own config via the +`configfile` setting of `linuxManualConfig`: + +```nix +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; +}; +``` + +You can edit the config with this snippet (by default `make + menuconfig` won\'t work out of the box on nixos): + +```ShellSession +nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' +``` + +or you can let nixpkgs generate the configuration. Nixpkgs generates it +via answering the interactive kernel utility `make config`. The answers +depend on parameters passed to +`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by +overriding `extraConfig, autoModules, + modDirVersion, preferBuiltin, extraConfig`). + +```nix +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 + ''; +}); +``` + +## Developing kernel modules {#sec-linux-config-developing-modules} + +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 `mellanox` drivers. + +```ShellSession +$ 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 +``` diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml deleted file mode 100644 index 529ac1b1cd4..00000000000 --- a/nixos/doc/manual/configuration/linux-kernel.xml +++ /dev/null @@ -1,138 +0,0 @@ -<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 kernel’s TCP keepalive time to 120 seconds. To see the available - parameters, run <command>sysctl -a</command>. - </para> - <section xml:id="sec-linux-config-customizing"> - <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 ++ [ pkg-config 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 xml:id="sec-linux-config-developing-modules"> - <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> -<prompt>$ </prompt>nix-build '<nixpkgs>' -A linuxPackages.kernel.dev -<prompt>$ </prompt>nix-shell '<nixpkgs>' -A linuxPackages.kernel -<prompt>$ </prompt>unpackPhase -<prompt>$ </prompt>cd linux-* -<prompt>$ </prompt>make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules -<prompt># </prompt>insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko -</screen> - </section> -</chapter> diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml new file mode 100644 index 00000000000..b9be041e59b --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml @@ -0,0 +1,153 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kernel-config"> + <title>Linux Kernel</title> + <para> + You can override the Linux kernel and associated packages using the + option <literal>boot.kernelPackages</literal>. For instance, this + selects the Linux 3.10 kernel: + </para> + <programlisting language="bash"> +boot.kernelPackages = pkgs.linuxPackages_3_10; +</programlisting> + <para> + 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: + </para> + <programlisting> +zcat /proc/config.gz +</programlisting> + <para> + If you want to change the kernel configuration, you can use the + <literal>packageOverrides</literal> feature (see + <xref linkend="sec-customising-packages" />). For instance, to + enable support for the kernel debugger KGDB: + </para> + <programlisting language="bash"> +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; +</programlisting> + <para> + <literal>extraConfig</literal> 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 <literal>udev</literal>. You can force a module to + be loaded via + <link xlink:href="options.html#opt-boot.kernelModules"><literal>boot.kernelModules</literal></link>, + e.g. + </para> + <programlisting language="bash"> +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +</programlisting> + <para> + If the module is required early during the boot (e.g. to mount the + root file system), you can use + <link xlink:href="options.html#opt-boot.initrd.kernelModules"><literal>boot.initrd.kernelModules</literal></link>: + </para> + <programlisting language="bash"> +boot.initrd.kernelModules = [ "cifs" ]; +</programlisting> + <para> + This causes the specified modules and their dependencies to be added + to the initial ramdisk. + </para> + <para> + Kernel runtime parameters can be set through + <link xlink:href="options.html#opt-boot.kernel.sysctl"><literal>boot.kernel.sysctl</literal></link>, + e.g. + </para> + <programlisting language="bash"> +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; +</programlisting> + <para> + sets the kernel’s TCP keepalive time to 120 seconds. To see the + available parameters, run <literal>sysctl -a</literal>. + </para> + <section xml:id="sec-linux-config-customizing"> + <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>: + </para> + <programlisting language="bash"> +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; +}; +</programlisting> + <para> + You can edit the config with this snippet (by default + <literal>make menuconfig</literal> won't work out of the box on + nixos): + </para> + <programlisting> +nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})' +</programlisting> + <para> + or you can let nixpkgs generate the configuration. Nixpkgs + generates it via answering the interactive kernel utility + <literal>make config</literal>. The answers depend on parameters + passed to + <literal>pkgs/os-specific/linux/kernel/generic.nix</literal> + (which you can influence by overriding + <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>). + </para> + <programlisting language="bash"> +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 + ''; +}); +</programlisting> + </section> + <section xml:id="sec-linux-config-developing-modules"> + <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> + <programlisting> +$ 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 +</programlisting> + </section> +</chapter> |