Kernel configuration
Changing the kernel configuration
You can change the kernel configuration with pmbootstrap. On some devices the naming convention is simply linux-<vendor>-<device>, for the linux-sony-yuga package for example we run:
pmbootstrap kconfig edit sony-yuga
Some devices do not follow this naming convention, in which case you can check what package provided the kernel by running:
apk info --who-owns /boot/vmlinuz-*
On the pinephone by pine64 you would run:
pmbootstrap kconfig edit linux-postmarketos-allwinner-5.4.0_git20191204-r1
This gives you a menu where you can select and deselect all kernel configuration options. Press the /
key to get a search dialog. After finding something, type the number of the search result to quickly jump to it.
If you don't like the terminal user interface, you can also use pmbootstrap kconfig edit -x
or pmbootstrap kconfig edit -g
. See pmbootstrap kconfig edit -h
for details.
Options aren't always visible!
If you're looking for an option and you just can't find it, then it might not show up because it depends on other options that have been disabled. In that case, press /
and search for the option in question. You will see the dependencies. Then use the search again to find these dependencies, and enable them until you can finally enable the option you wanted to change in the first place.
Useful kernel configuration options
Required to be enabled/disabled
Enable or disable the following options to get postmarketOS working. Use pmbootstrap kconfig check
to check which options need to be modified.
CONFIG_DEVTMPFS
About
This adds support for the devtmpfs filesystem which should be mounted to /dev at startup. 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.
Location in menu
Device Drivers --> Generic Driver Options --> Maintain a devtmpfs filesystem to mount at /dev
pmOS specific
This should always be set, otherwise you get this when you try SSH:
PTY allocation request failed on channel 0 -ash: a: unknown operand
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>.
Location in menu
Device Drivers --> Character Devices --> Enable TTY --> Virtual Terminal
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.
Location in menu
Device Drivers --> Multiple devices driver support (RAID and LVM) --> Device mapper support --> Crypt target support
pmOS specific
This should always be set, required for full disk encyption.
CONFIG_EXT4_FS
About
This is the next generation of the ext3 filesystem.
Location in menu
File systems --> The Extended 4 (ext4) filesystem
pmOS specific
This should always be set since pmbootstrap creates an ext4 rootfs.
CONFIG_UEVENT_HELPER
About
The uevent helper program is forked by the kernel for every uevent. Before the switch to the netlink-based uevent source, this was used to hook hotplug scripts into kernel device events. It usually pointed to a shell script at /sbin/hotplug. This should not be used today, because usual systems create many events at bootup or device discovery in a very short time frame. One forked process per event can create so many processes that it creates a high system load, or on smaller systems it is known to create out-of-memory situations during bootup.
Location in menu
Device Drivers --> Generic Driver Options --> Support for uevent helper
pmOS specific
This option should always be enabled on pmos kernels that are 3.16+, it's the config option that makes /proc/sys/kernel/hotplug appear.
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.
- 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.
- 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.
- 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.
- Read more...
Location in menu
General Setup --> Kernel compression mode --> Gzip LZMA XZ LZO
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#Kernel_compilation:_BusyBox_lzma_compression_fails.
- XZ: Make sure to add
xz
tomakedepends
in the APKBUILD of your kernel package. - LZO: If you get
lzop: high compression not compiled in
during compilation of the kernel you probably need this patch.
CONFIG_ANDROID_PARANOID_NETWORK
About
Android adds a "paranoid network" option to the Linux kernel, which restricts access to some networking features depending on the group of the calling process. The list of groups that are allowed access to networking features is in the kernel source file: /include/linux/android_aids.h Setting this config will enable the paranoid network security feature
Location in menu
Networking Support --> Networking Options --> Only allow certain groups to create sockets
Android specific
This option should not be set in pmOS or any other OS not using Android security model.
CONFIG_PFT
About
This caused builds to fail with a modern GCC at least once, and while it originally was meant as security feature by Qualcomm, "it is unsupported by Qualcomm, and opens up to a wide range of potential attack surfaces that has not been audited by anyone." [1].
Location in menu
Device Drivers --> Qualcomm MSM specific device drivers --> Per-File-Tagger driver
pmOS specific
Please disable it, so we have one less source for failing builds and enabling it has no benefit anyway.
CONFIG_SYSVIPC
Location in menu
General Setup --> System V IPC
pmOS specific
Please enable it for postmarketOS, so busybox' syslogd can log to a ringbuffer in the kernel (fixes #808).
CONFIG_USE_VFB
About
Weston and Plasma Mobile might choose to draw on this virtual frame buffer, just like it happened for the samsung-jflte (pmaports#34). Disabling the USE_VFB option fixed this, so let's make sure we don't have that option enabled for any kernel.
Location in menu
Device Drivers --> Graphics supports --> MSM Framebuffer support --> MSM Virtual Framebuffer support
pmOS specific
Please disable it, so we have one less source of failure.
CONFIG_KINETO_GAN
About
Related to a proprietary "T-Mobile's WiFi-Calling" feature. It should not affect normal calls, so it should be safe to disable it.
Location in menu
Device Drivers --> Network device support --> Kineto GAN virtual network interface
pmOS specific
Causes sudo
, ip
and other commands to hang (pmaports#1513). Please disable it.
CONFIG_BLK_DEV_INITRD
About
Initial RAM filesystem and RAM disk (initramfs/initrd) support
Location in menu
General setup --> Initial RAM filesystem and RAM disk (initramfs/initrd) support
pmOS specific
Required. See pmaports#237 for notes about changing the initramfs compression.
CONFIG_CGROUPS
About
This option adds support for grouping sets of processes together, for use with process control subsystems such as Cpusets, CFS, memory controls or device isolation.
Location in menu
General setup --> Control Group support
pmOS specific
Required for elogind, and therefore necessary to be able to run most desktop environments.
Optional
These kernel options are optional and for some devices required to fix some issues.
CONFIG_LBDAF
About
Support for large (2TB+) block devices and files
The ext4 filesystem requires that this feature be enabled in order to support filesystems that have the huge_file feature enabled. Otherwise, it will refuse to mount in the read-write mode any filesystems that use the huge_file feature, which is enabled by default by mke2fs.ext4.
Location in menu
-*- Enable the block layer ---> [*] Support for large (2TB+) block devices and files
pmOS specific
This is recommended for all 32bit (armhf, x86) devices. The option is not present on 64bit (aarch64, x86_64) devices.
Without this option, it is not possible to mount ext4 partitions that have been created with the default settings. The postmarketOS SD card installation uses these default parameters. There doesn't seem to be a point in changing that to work around badly configured kernels: even if the postmarketOS installation did not require this option, you might come across an SD card with ext4, that does not work on your device.
CONFIG_USB_G_ANDROID
About
The Android Composite Gadget supports multiple USB functions: adb, acm, mass storage, mtp, accessory and rndis.
Each function can be configured and enabled/disabled dynamically from userspace through a sysfs interface.
Location in menu
Device Drivers --> USB Support --> USB Gadget Support --> USB Gadget Drivers --> Android Composite Gadget
pmOS specific
Enabling this option is needed for usb networking on some of the android kernels.
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.
Location in menu
Device Drivers --> USB Support --> USB Gadget Support --> USB Gadget Drivers --> Ethernet Gadget
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.
Location in menu
Device Drivers --> USB Support --> USB Gadget Support --> USB Gadget Drivers --> RNDIS Support
pmOS specific
Required if you set CONFIG_USB_ETH
to 'Y'.
CONFIG_MSM_KGSL
About
3D graphics driver. Required to use hardware accelerated OpenGL ES 2.0 and 1.1.
Location in menu
Device Drivers --> Graphics Support --> MSM 3D graphics Driver
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.
Location in menu
General Setup --> Boot options --> Default kernel command string
pmOS specific
No
CONFIG_FHANDLE
About
open by fhandle syscalls
Location in menu
General setup --> open by fhandle syscalls
pmOS specific
If USB OTG isn't working for you, try enable this config.
CONFIG_BUILD_ARM_APPENDED_DTB_IMAGE
About
Build a concatenated zImage/dtb by default
Enabling this option will cause a concatenated zImage and list of DTBs to be built by default (instead of a standalone zImage.)
The image will built in arch/arm/boot/zImage-dtb
Location in menu
General Setup --> Boot options --> appended device tree blob to zImage
pmOS specific
Set this if your device needs an appended device tree. If you are unsure, use extract-dtb
on an existing kernel image. Not to be confused with CONFIG_ARM_APPENDED_DTB
!
CONFIG_FW_LOADER_USER_HELPER
About
Enable the firmware sysfs fallback mechanism found in drivers/base/firmware_loader/Kconfig
Location in menu
Device Drivers --> Generic Driver Options --> Firmware loader --> Firmware loading facility (FW_LOADER [=y]) --> Enable the firmware sysfs fallback mechanism
pmOS specific
Prior to kernel version 3.7, the kernel had no capability of finding firmware itself so it had to call out to userspace to find the firmware for it. This changed with kernel 3.7 where the kernel gained "direct loading support" and where the userspace helper was only called as a fallback. In kernel 3.9 this functionality was put behind the kconfig option FW_LOADER_USER_HELPER which is what this patch checks to be enabled.
Without this option, the udev rule present in postmarketos-base won't be notified that firmware needs to be loaded and as such can't call firmwareload.sh which loads firmware from /lib/firmware/postmarketos.
CONFIG_KEY_DH_OPERATIONS & CONFIG_CRYPTO_DH & CONFIG_CRYPTO_DES & CONFIG_CRYPTO_USER_API_SKCIPHER
About
These options enables ability to use iwd daemon (wpa_supplicant replacement)
Location in menu
Security Options ---> [*] Enable access key retention support [*] Diffie-Hellman operations on retained keys Cryptographic API ---> [*] Diffie-Hellman algorithm [*] DES and Triple DES EDE cipher algorithms [*] User-space interface for symmetric key cipher algorithms
and these
CONFIG_CRYPTO_USER_API_HASH CONFIG_CRYPTO_ECB CONFIG_CRYPTO_MD4 CONFIG_CRYPTO_MD5 CONFIG_CRYPTO_CBC CONFIG_CRYPTO_SHA1 CONFIG_CRYPTO_SHA256 CONFIG_CRYPTO_SHA512 CONFIG_CRYPTO_AES CONFIG_CRYPTO_DES CONFIG_CRYPTO_CMAC CONFIG_CRYPTO_HMAC CONFIG_CRYPTO_ARC4
pmOS specific Enable only on recent mainline kernels. After enabling these options, you can use iwd daemon (better performance) instead of wpa_supplicant.
CONFIG_USER_NS
About
User namespace
Required for BubbleWrap sandboxing used by The GNOME Web (Epiphany) and other software.
pmOS specific
Phosh environment must have it enabled for Web browser (Epiphany) being functional.
SECCOMP
About
Enable seccomp to safely compute untrusted bytecode
Required for BubbleWrap sandboxing used by The GNOME Web (Epiphany) and other software.
pmOS specific
Phosh environment must have it enabled for Web browser (Epiphany) being functional.