From 8f5f696de5498dc394f36be0897c8187dd5ee375 Mon Sep 17 00:00:00 2001
From: Aelin <aelin@postmarketos.org>
Date: Mon, 26 Jan 2026 00:25:09 +0100
Subject: [PATCH] docs: Add documentation on generic kernels

Part-of: <https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/7842>
---
 docs/generic-kernels.md | 71 +++++++++++++++++++++++++++++++++++++++++
 docs/index.md           |  1 +
 2 files changed, 72 insertions(+)
 create mode 100644 docs/generic-kernels.md

diff --git a/docs/generic-kernels.md b/docs/generic-kernels.md
new file mode 100644
index 000000000..70a7d7627
--- /dev/null
+++ b/docs/generic-kernels.md
@@ -0,0 +1,71 @@
+# Generic Kernels
+
+postmarketOS includes a couple of generic kernel packages in the `main` device
+category: `linux-postmarketos-mainline`, `linux-postmarketos-stable` and
+`linux-postmarketos-lts`.
+
+These are kernels intended to work on a wide variety of devices and are the
+postmarketOS equivalents to Alpine kernels such as `linux-stable` or
+`linux-lts`. Having these kernels in postmarketOS means that we have full
+control over the kernel configuration and build process, which allows us to
+integrate them with our [kernel configuration checks](./kconfigcheck).
+
+In the long term, all devices using Alpine kernels should be migrated to the
+postmarketOS generic kernels.
+
+## Configuration
+
+Since it would be very tedious to manually update the configuration for
+multiple kernel packages individually, the configuration for the kernels is
+automatically generated from two sources in pmaports:
+
+* `kconfigcheck.toml`, to make sure that they pass our checks
+* `kconfig-generic.toml`, a file to enable device-specific drivers and apply
+  opinionated configurations
+
+The former is a file used by pmbootstrap to verify the configuration of all
+kernels in pmaports, the latter is a file specifically for the configuration of
+the generic kernel packages.
+
+`pmbootstrap kconfig generate` will look at both of these files and generate a
+fragment for each of them, which are then merged with the default `defconfig`
+for an architecture in the Linux kernel.
+
+## Adding new options
+
+If a required option for your device is missing in the generic kernels, take a
+moment to consider whether this is an option that *all* kernels in postmarketOS
+should have enabled. If that's the case, then you should open a MR to add it
+to `kconfigcheck.toml`, see [the documentation](./kconfigcheck) on the topic
+for further details.
+
+If that's not the case, then it is probably a good fit for
+`kconfig-generic.toml`. Suppose your device has an Omnivision 8856 camera and
+you'd like to enable the driver for it: In Linux, this requires setting
+`CONFIG_VIDEO_OV8856=m` in the kernel configuration.
+
+Check whether `kconfig-generic.toml` has an existing category that seems to fit
+this configuration option (for example, `category:video`). If not, add a new
+one, otherwise add it to the existing category. Categories in this TOML file
+only exist for grouping things together, no filtering is performed, so don't
+think too much about it.
+
+If this configuration option was only added recently, find out since when it
+exists in Linux. Also, make sure to check whether it can be enabled on all
+architectures or only on select few.
+
+You can then add to `kconfig-generic.toml`:
+
+```toml
+["category:video".">=6.12_rc1"."all"]
+VIDEO_OV8856 = "m"
+```
+
+This would result in `CONFIG_VIDEO_OV8856=m` being set for all generic kernels
+newer than 6.12-rc1 and enable it on all architectures.
+
+You can submit your change in a GitLab MR for the generic kernel maintainers to
+review. Please do **not** regenerate the kernel configurations; your change
+will be included as part of the next kernel upgrade. Rebuilds of the kernel
+packages take a long time and they get updated regularly, so you'll only need
+to wait a few days until your change makes it into the released binaries.
diff --git a/docs/index.md b/docs/index.md
index 0126654f2..09c415751 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,6 +17,7 @@ in pmaports and the processes around device categorization.
    device-categorization
    deviceinfo-reference
    ci-tags
+   generic-kernels
    kconfigcheck
    kernel-cmdline
    kernel-versions