From a80206516ee8dd179ef73de4e94790f6b8d4c934 Mon Sep 17 00:00:00 2001 From: Clayton Craft Date: Mon, 12 Jan 2026 11:01:31 -0800 Subject: [PATCH] docs/kernel-cmdline: add docs for new kernel cmdline system Signed-off-by: Clayton Craft Part-of: --- docs/index.md | 1 + docs/kernel-cmdline.md | 108 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 docs/kernel-cmdline.md diff --git a/docs/index.md b/docs/index.md index 1a2c78792..0126654f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,5 +18,6 @@ in pmaports and the processes around device categorization. deviceinfo-reference ci-tags kconfigcheck + kernel-cmdline kernel-versions ``` diff --git a/docs/kernel-cmdline.md b/docs/kernel-cmdline.md new file mode 100644 index 000000000..5a8d0c121 --- /dev/null +++ b/docs/kernel-cmdline.md @@ -0,0 +1,108 @@ +# Kernel Command Line Configuration + +## Overview + +The kernel command line in postmarketOS is generated by boot-deploy calling `generate-kernel-cmdline`. This tool combines configuration from multiple sources following a three-tier hierarchy: distro defaults, device maintainer config, and user overrides. + +The previous system using deviceinfo variables had several limitations. First, boot-deploy is distro-agnostic, so any defaults there must apply to all supported distros. This limited what could be added (kernel lockdown, plymouth splash, etc). Second, the deviceinfo keys could only add parameters, not remove them. This made it problematic for users to override kernel cmdline params installed by packaging. + +The new system addresses these issues by supporting both adding and removing specific kernel parameters, providing a clear configuration hierarchy with well-defined ordering, and allowing packages to define their own cmdline config without modifying shared defaults (similar to how initramfs files are handled). + +For details on the configuration file format, see `man 5 generate-kernel-cmdline` or the [online documentation](https://gitlab.postmarketos.org/postmarketOS/generate-kernel-cmdline/-/blob/main/docs/generate-kernel-cmdline.5.md). + +## Migration from deviceinfo + +To migrate a device package from the old system: + +1. Remove `deviceinfo_kernel_cmdline=` from the device's `deviceinfo` file +2. Create a `kernel-cmdline.conf` file in the device package directory listing the parameters (one per line) +3. Add `kernel-cmdline.conf` to `source=` in the APKBUILD + +For example, if deviceinfo had: +``` +deviceinfo_kernel_cmdline="quiet loglevel=2 clk_ignore_unused" +``` + +Create `kernel-cmdline.conf`: +``` +quiet +loglevel=2 +clk_ignore_unused +``` + +## Device Package Configuration + +Device maintainers can add kernel command line parameters specific to their device by creating a `kernel-cmdline.conf` file in the device package directory and adding it to `source=` in the APKBUILD. The devicepkg-dev tool will automatically install this file to `/usr/lib/kernel-cmdline.d/50-.conf` during package build. This works similarly to how `modules-initfs` files are handled. + +The configuration file lists kernel parameters one per line. Parameters can be added or removed (prefix with `-` to remove). + +Example `kernel-cmdline.conf`: +``` +console=ttyMSM0,115200 +clk_ignore_unused +pd_ignore_unused +``` + +## User Overrides + +Users and system administrators can override kernel command line configuration by creating files in `/etc/kernel-cmdline.d/`. Files must have a `.conf` extension and are processed in lexicographic order after distro and device configs. + +To add parameters, create a config file: +``` +doas $EDITOR /etc/kernel-cmdline.d/custom.conf +``` + +To remove a parameter that was set by distro or device config, prefix it with `-`: +``` +-quiet +debug +``` + +## Verification + +Users can verify the generated kernel command line by running `generate-kernel-cmdline` as an unprivileged user: +``` +$ generate-kernel-cmdline +quiet hid_apple.swap_fn_leftctrl=1 splash +``` + +Note that this only shows parameters from configuration files. It does not include parameters that boot-deploy injects at install time. + +## Examples + +### Base Distro Config + +`/usr/lib/kernel-cmdline.d/00-base.conf`: +``` +quiet +splash +``` + +### Device Config + +`/usr/lib/kernel-cmdline.d/50-device-pine64-pinephone.conf`: +``` +console=ttyMSM0,115200 +``` + +Result: `quiet splash console=ttyMSM0,115200` + +### User Override for Debugging + +`/etc/kernel-cmdline.d/debug.conf`: +``` +-quiet +debug +loglevel=7 +``` + +Result: `splash console=ttyMSM0,115200 debug loglevel=7` + +### User Hardware Configuration + +`/etc/kernel-cmdline.d/keyboard.conf`: +``` +hid_apple.swap_fn_leftctrl=1 +``` + +Result: `splash console=ttyMSM0,115200 debug loglevel=7 hid_apple.swap_fn_leftctrl=1`