docs/kernel-cmdline: add docs for new kernel cmdline system

Signed-off-by: Clayton Craft <craftyguy@postmarketos.org>
Part-of: <https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/7708>

docs/index.md

@@ -18,5 +18,6 @@ in pmaports and the processes around device categorization.
    deviceinfo-reference
    ci-tags
    kconfigcheck
+   kernel-cmdline
    kernel-versions
 ```

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-<device>.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`