initial commit

1 files changed, 128 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8f2c9f0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# kernel-surface
+
+A Fedora kernel RPM for the Microsoft Surface Pro 12" Gen 1 (Snapdragon
+X1P-42-100): vanilla upstream Linux with the device's patch set from the
+[miasvanklei Gentoo overlay](https://github.com/miasvanklei/Gentoo-overlay)
+applied.
+
+Used in [Fedora KIWI descriptions, modified by me for Surface Pro 12"](https://sayag.it/fedora-linux-surface-pro-12in/kiwi-descriptions).
+
+## What gets applied
+
+`patch-order.txt` lists the patch directories in the order the overlay's
+`vanilla-kernel-*.ebuild` applies them, minus `gpu` (does not exist) and
+`rockchip` (irrelevant).
+
+## Configuration
+
+The starting point is `config/base-aarch64.config`: Fedora's own aarch64
+kernel config, taken verbatim from the `config` file inside
+`kernel-core-7.2.0-61.fc45.aarch64.rpm`. It is vendored rather than downloaded,
+so the build depends on no third-party host and a refresh shows up as a
+reviewable diff. To refresh it for a newer Fedora, replace everything below the
+comment header with:
+
+```bash
+dnf download kernel-core --arch aarch64
+rpm2cpio kernel-core-*.aarch64.rpm | cpio -idm './usr/lib/modules/*/config'
+```
+
+The overlay's ebuild seeds itself from the same Fedora config by way of a
+Gentoo-side fork, `projg2/fedora-kernel-config-for-gentoo`. That repository no
+longer exists, which is why the base config lives here instead.
+
+Three fragments are merged on top with `scripts/kconfig/merge_config.sh`:
+
+* `config/surface.config` – the drivers the patch set enables (SAM stack and
+  its new RTC, CAMSS and the CSI-2 D-PHY, fastrpc, ath12k, AudioReach).
+* `config/live-image.config` – what the KIWI image types need: erofs with lzma
+  and dm-snapshot/overlayfs built in for `dracut`'s `dmsquash-live`, the EFI
+  stub because GRUB's aarch64 `linux` command loads the kernel as an EFI
+  application, and xz module compression.
+* `config/no-debug-info.config` – DWARF and BTF off. The package produces no
+  `-debuginfo` subpackage (`%global debug_package %{nil}`) and strips modules
+  at install time, so the DWARF was compiled only to be discarded, and it is
+  what makes the build too big for the 6 CPU / 8 GB arm64 builder. The cost is
+  BTF, the one part that would have shipped: no `/sys/kernel/btf/vmlinux`, so
+  eBPF CO-RE tooling does not work, and `CONFIG_BPF_LSM` switches itself off
+  with it, which disables systemd settings such as `RestrictFileSystems=`.
+
+`%prep` also resets `CONFIG_BUILD_SALT`, which the base config inherits from
+the Fedora build it came from, and which feeds the kernel's build ID.
+
+`%prep` then asserts that `CONFIG_RTC_DRV_SURFACE` and
+`CONFIG_PHY_QCOM_MIPI_CSI2` made it into `.config`. Those symbols only exist if
+the patch set applied, so a silently mis-applied patch fails the build instead
+of producing a kernel that is quietly missing drivers.
+
+There is no module signing and the kernel is not signed for Secure Boot, which
+matches the ISO (the project README notes Secure Boot is not available for it).
+
+## Installing
+
+```bash
+dnf config-manager addrepo --from-repofile=\
+  https://f003.backblazeb2.com/file/dist-sayagit-fedora-rpm/fedora/45/kernel-sp12in.repo
+```
+
+## Building
+
+The build must run on aarch64 – `ExclusiveArch: aarch64`. On an x86_64 host,
+use `binfmt`-based emulation, at a large cost in build time.
+
+```bash
+# Fetch the miasvanklei/Gentoo-overlay
+git submodule update --init overlay
+
+# Collect the patch tarball, the kernel tarball and the configs
+./make-sources.sh
+
+# Build
+sudo dnf builddep kernel-surface.spec
+rpmbuild -bb kernel-surface.spec
+```
+
+The build is pinned to `-j4` rather than the node's CPU count, because four
+parallel compilers is what the builder's memory limit holds:
+
+```bash
+rpmbuild -bb --define '_smp_mflags -j4' kernel-surface.spec
+```
+
+`make-sources.sh -n` skips the downloads and only rebuilds the patch tarball,
+which is what you want while iterating on `patch-order.txt`. `-o DIR` writes
+somewhere other than rpm's `%_sourcedir`.
+
+To move to a newer kernel, change `%global upstream_ver` in the spec, update the
+`overlay` submodule, and re-run `make-sources.sh`. `%global patchset_ver` is for
+the case where the patches change but the kernel version does not.
+
+### Package layout
+
+One binary package with the kernel image, every module and the device trees. It
+does not reproduce Fedora's `kernel-core` / `kernel-modules` /
+`kernel-modules-extra` split – for a single-device image there is nothing to
+gain from it, and the split is driven by module lists that would need to be
+maintained by hand.
+
+It `Provides` all three of those names plus `kernel` and the `*-uname-r` forms,
+so packages that `Requires: kernel-core` resolve against it. It deliberately
+does **not** `Obsoletes` them: the KIWI description selects it by name, which
+keeps the repository safe to enable on a normal Fedora system without hijacking
+kernel updates there.
+
+## Releasing
+
+The Jenkinsfile builds and publishes nothing except for tags of the form
+`fedora-<fedora_ver>-kernel-<upstream_ver>-patchset-<patchset_ver>`, e.g.
+`fedora-45-kernel-7.2.3-patchset-1`. If it is `rawhide`, use the latest Fedora
+tag (on the moment of writing this it was `46`).
+
+The Fedora version selects both the build container and the bucket prefix, and
+is checked against the container's own `%{fedora}` for a numbered release.
+
+What the tag does *not* override is the `overlay` submodule, and the patch set
+there is written against one kernel version. Tagging a kernel the pinned overlay
+commit does not target gets a `%prep` full of rejected patches – see the
+`patch-order.txt` and `%if %{undefined}` comments for how the two are kept in
+step.