# 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 packages with that support multiple kernels should name the file `kernel-cmdline.<kernel name>.conf` and add it to `sources=` in the APKBUILD. No other action is needed, this file will be automatically added to the correct subpackage by `devicepkg-dev`.

## 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:
```
sudo $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`
