Jump to content

Kernel configuration: Difference between revisions

From postmarketOS Wiki
Wfranken (talk | contribs)
Knuxify (talk | contribs)
use PrefixIndex for subpages
 
(103 intermediate revisions by 35 users not shown)
Line 1: Line 1:
{{note|This page is WIP.}}
<!--


= Changing the kernel configuration =
NOTE for editors:


You can change the kernel configuration with pmbootstrap, for the sony-yuga device for example we run:
This page is just an overview, please keep it lean and refer to other pages for details! Feel free to create more "Kernel configuration/ ..." pages as it makes sense.


<pre class="shell">./pmbootstrap.py menuconfig linux-sony-yuga</pre>
-->
Kernel configurations determine which features of the Linux kernel are enabled for a particular build, such as filesystems, camera, WiFi related options and a lot more. This article gives an overview of how kernel configs are managed in postmarketOS and how one can change them.


This gives you a menu where you can select and deselect all kernel configuration options:
== Why do we have multiple kernel configs? ==
We would ideally run [[PostmarketOS_Trailblazer_(postmarketos-trailblazer)|mainline Linux without any patches]] on all devices and only have one kernel config per device architecture. But oftentimes we need to carry a few patches for our [[(Close to) Mainline]] kernels (used for devices in ''main'' and ''community'' [[Device_categorization|categories]]). Another reason is that in many cases want to be on a specific, known-working version before we upgrade to the next one. Furthermore devices in the ''testing'' category may just use the downstream kernel to get the device booting at all. Because of that, you will find ''a lot'' of Linux kernels when looking at the postmarketOS specific package build recipes in [[pmaports.git]].


[[File:KernelConfig.png|800px]]
== Keeping kernel configs consistent ==


= Useful kernel configuration options =
All kernel configs are stored inside pmaports (list them with <code>find device -name 'config-*'</code>). We ensure that they have [[Kernel configuration/Specific options|specific options]] enabled, disabled or set to a certain value with a CI script that essentially runs <code>pmbootstrap kconfig check</code>. This [[pmbootstrap]] command reads our requirements from <code>kconfigcheck.toml</code> in the currently checked out pmaports branch and verifies that all kernels pass the requirements. See [[Kernel configuration/Adjusting multiple kernels]] for more information.


== Required ==
=== Future plans ===


These kernel options must be set for pmOS to work.
At some point we would like to generate the kernel configs for ''main'' and ''community'' devices from fragments. Work on this has been started in {{issue|2492|pmaports}} (big thanks to Jenneron and everybody involved!). However this is quite the big undertaking and work has stalled. So we decided to improve and document the current process instead, which we will still need for devices in ''testing'' in any case.


=== CONFIG_DEVTMPFS ===
== Adjusting one kernel config ==


'''About'''
It is recommended to change kernel config options not just for one kernel, but for all where it makes sense (typically all devices in the ''community'' or ''main'' category as explained [[Kernel configuration/Adjusting multiple kernels|here]]). However before you do that, you should first edit the one kernel you are currently using on your device to test if the change has the desired effect.


''This creates a tmpfs filesystem, and mounts it at bootup and mounts it at /dev. The kernel driver core creates device nodes for all registered devices in that filesystem. All device nodes are owned by root and have the default mode of 0600. Userspace can add and delete the nodes as needed.''
You basically need to run <code>pmbootstrap kconfig edit</code> followed by the name of the kernel package, see [[Kernel configuration/Adjusting one kernel]] for details.


[https://cateee.net/lkddb/web-lkddb/DEVTMPFS.html Read more...]
== Subpages ==


'''Location in menu'''
{{Special:PrefixIndex/Kernel configuration/|hideredirects=yes}}


<pre class="shell>
[[Category: Technical Reference]]
Device Drivers -->
  Generic Driver Options -->
    Maintain a devtmpfs filesystem to mount at /dev
</pre>
 
'''pmOS specific'''
 
This should always be set, otherwise you get this when you try SSH:
 
<pre>PTY allocation request failed on channel 0
-ash: a: unknown operand</pre>
 
=== CONFIG_DEVTMPFS_MOUNT ===
 
'''About'''
 
''This will instruct the kernel to automatically mount the devtmpfs filesystem at /dev, directly after the kernel has mounted the root filesystem. The behavior can be overridden with the commandline parameter: devtmpfs.mount=0|1.''
 
[https://cateee.net/lkddb/web-lkddb/DEVTMPFS_MOUNT.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
Device Drivers -->
  Generic Driver Options -->
    Automount devtmpfs at /dev, after the kernel mounted the rootfs
</pre>
 
'''pmOS specific'''
 
This option should '''not''' be set.
 
=== CONFIG_VT ===
 
'''About'''
 
''If you say Y here, you will get support for terminal devices with display and keyboard devices. These are called "virtual" because you can run several virtual terminals (also called virtual consoles) on one physical terminal. This is rather useful, for example one virtual terminal can collect system messages and warnings, another one can be used for a text-mode user session, and a third could run an X session, all in parallel. Switching between virtual terminals is done with certain key combinations, usually Alt-<function key>.''
 
[https://cateee.net/lkddb/web-lkddb/VT.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
Device Drivers -->
  Character Devices -->
    Virtual Terminal
</pre>
 
'''pmOS specific'''
 
This should always be set, otherwise you cannot get virtual terminal over USB.
 
=== CONFIG_DM_CRYPT ===
 
'''About'''
 
''This device-mapper target allows you to create a device that transparently encrypts the data on it.''
 
[https://cateee.net/lkddb/web-lkddb/DM_CRYPT.html Read more...]
 
'''Location in menu'''
 
Does not exist in menu
 
'''pmOS specific'''
 
This should always be set, required for full disk encyption.
 
=== CONFIG_KERNEL_GZIP, CONFIG_KERNEL_XZ, CONFIG_KERNEL_LZO and CONFIG_KERNEL_LZMA ===
 
'''About'''
 
;GZIP
:  ''The old and tried gzip compression. It provides a good balance between compression ratio and decompression speed.''
[https://cateee.net/lkddb/web-lkddb/KERNEL_GZIP.html Read more...]
;XZ
:  ''XZ uses the LZMA2 algorithm and instruction set specific BCJ filters which can improve compression ratio of executable code. The size of the kernel is about 30% smaller with XZ in comparison to gzip. The speed is about the same as with LZMA: The decompression speed of XZ is better than that of bzip2 but worse than gzip and LZO. Compression is slow.''
:  [https://cateee.net/lkddb/web-lkddb/KERNEL_XZ.html Read more...]
;LZO
:  ''Its compression ratio is the poorest among the choices. The kernel size is about 10% bigger than gzip; however its speed (both compression and decompression) is the fastest.''
:  [https://cateee.net/lkddb/web-lkddb/KERNEL_LZO.html Read more...]
;LZMA
:  ''This compression algorithm's ratio is best. Decompression speed is between gzip and bzip2. Compression is slowest. The kernel size is about 33% smaller with LZMA in comparison to gzip.''
:  [https://cateee.net/lkddb/web-lkddb/KERNEL_LZMA.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
General Setup -->
  Kernel compression mode -->
    Gzip
    LZMA
    XZ
    LZO
</pre>
 
'''pmOS specific'''
 
You should set one of these to Y.
* Gzip: Works without specifying anything else.
* LZMA: If kernel compilation fails with this compression type, read [[Troubleshooting:kernel]].
* XZ: Make sure to add <code>xz</code> to <code>makedepends</code> in the APKBUILD of your kernel package.
* LZO: If you get <code>lzop: high compression not compiled in</code> during compilation of the kernel you probably need [https://github.com/postmarketOS/pmbootstrap/blob/b4c9f93f0d7be1272f6a67de2128558ce58e1077/aports/linux-samsung-i9070/02_reduce_lzo_compression.patch this patch].
 
== Optional ==
 
These kernel options are optional and for some devices required to fix some issues.
 
=== CONFIG_USB_ETH ===
 
'''About'''
 
''This driver implements Ethernet style communication, in one of several ways:
 
* ''The "Communication Device Class" (CDC) Ethernet Control Model. That protocol is often avoided with pure Ethernet adapters, in favor of simpler vendor-specific hardware, but is widely supported by firmware for smart network devices.''
* ''On hardware can't implement that protocol, a simple CDC subset is used, placing fewer demands on USB.''
* ''CDC Ethernet Emulation Model (EEM) is a newer standard that has a simpler interface that can be used by more USB hardware.''
 
''RNDIS support is an additional option, more demanding than than subset.''
 
[https://cateee.net/lkddb/web-lkddb/USB_ETH.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
Device Drivers -->
  USB Support -->
    USB Gadget Support -->
      USB Gadget Drivers -->
        Ethernet Gadget
</pre>
 
'''pmOS specific'''
 
Most devices do not need this to be set. If telnet/SSH does not work you can try and set this option to Y.
 
=== CONFIG_USB_ETH_RNDIS ===
 
'''About'''
 
''Microsoft Windows XP bundles the "Remote NDIS" (RNDIS) protocol, and Microsoft provides redistributable binary RNDIS drivers for older versions of Windows.''
 
''If you say "y" here, the Ethernet gadget driver will try to provide a second device configuration, supporting RNDIS to talk to such Microsoft USB hosts.''
 
[https://cateee.net/lkddb/web-lkddb/USB_ETH_RNDIS.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
Device Drivers -->
  USB Support -->
    USB Gadget Support -->
      USB Gadget Drivers -->
        RNDIS Support
</pre>
 
'''pmOS specific'''
 
Required if you set <code>CONFIG_USB_ETH</code> to 'Y'.
 
=== CONFIG_MSM_KGSL ===
 
'''About'''
 
''3D graphics driver. Required to use hardware accelerated OpenGL ES 2.0 and 1.1.''
 
[https://android.googlesource.com/kernel/msm/+/android-msm-mako-3.4-jb-mr1-kgsl/drivers/gpu/msm/Kconfig Read more...]
 
'''Location in menu'''
 
<pre class="shell>
Device Drivers -->
  Graphics Support -->
    MSM 3D graphics Driver
</pre>
 
'''pmOS specific'''
 
If framebuffer does not work set this to 'N'
 
=== CONFIG_CMDLINE ===
 
'''About'''
 
''Enter arguments here that should be compiled into the kernel image and used at boot time. If the boot loader provides a command line at boot time, it is appended to this string to form the full kernel command line, when the system boots.''
 
[https://cateee.net/lkddb/web-lkddb/CMDLINE.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
General Setup -->
  Boot options -->
    Default kernel command string
</pre>
 
'''pmOS specific'''
 
No
 
=== CONFIG_ARM_APPENDED_DTB ===
 
'''About'''
 
''With this option, the boot code will look for a device tree binary (DTB) appended to zImage (e.g. cat zImage <filename>.dtb > zImage_w_dtb).''
 
[https://cateee.net/lkddb/web-lkddb/ARM_APPENDED_DTB.html Read more...]
 
'''Location in menu'''
 
<pre class="shell>
General Setup -->
  Boot options -->
    Flattened Device Tree support
    Use appended device tree blob to zImage
</pre>
 
'''pmOS specific'''
 
Set this if your device need an appended device tree. If you are unsure, use <code>extract-dtb</code> on an existing kernel image.
 
= References =
 
# [https://cateee.net/lkddb/web-lkddb/ Linux Kernel Driver Database]

Latest revision as of 12:29, 3 September 2024

Kernel configurations determine which features of the Linux kernel are enabled for a particular build, such as filesystems, camera, WiFi related options and a lot more. This article gives an overview of how kernel configs are managed in postmarketOS and how one can change them.

Why do we have multiple kernel configs?

We would ideally run mainline Linux without any patches on all devices and only have one kernel config per device architecture. But oftentimes we need to carry a few patches for our (Close to) Mainline kernels (used for devices in main and community categories). Another reason is that in many cases want to be on a specific, known-working version before we upgrade to the next one. Furthermore devices in the testing category may just use the downstream kernel to get the device booting at all. Because of that, you will find a lot of Linux kernels when looking at the postmarketOS specific package build recipes in pmaports.git.

Keeping kernel configs consistent

All kernel configs are stored inside pmaports (list them with find device -name 'config-*'). We ensure that they have specific options enabled, disabled or set to a certain value with a CI script that essentially runs pmbootstrap kconfig check. This pmbootstrap command reads our requirements from kconfigcheck.toml in the currently checked out pmaports branch and verifies that all kernels pass the requirements. See Kernel configuration/Adjusting multiple kernels for more information.

Future plans

At some point we would like to generate the kernel configs for main and community devices from fragments. Work on this has been started in pmaports#2492 (big thanks to Jenneron and everybody involved!). However this is quite the big undertaking and work has stalled. So we decided to improve and document the current process instead, which we will still need for devices in testing in any case.

Adjusting one kernel config

It is recommended to change kernel config options not just for one kernel, but for all where it makes sense (typically all devices in the community or main category as explained here). However before you do that, you should first edit the one kernel you are currently using on your device to test if the change has the desired effect.

You basically need to run pmbootstrap kconfig edit followed by the name of the kernel package, see Kernel configuration/Adjusting one kernel for details.

Subpages