danctnix-besser-pkgbuild/README.md

@@ -6,7 +6,9 @@ Drop-in replacement for `linux-pinetab2`. Same kernel version, same config, same
 
 ## What's in the patchset
 
-A 16-commit cumulative diff over `v7.0-danctnix1`'s in-tree `drivers/staging/bes2600/`, capturing:
+A 16-commit cumulative diff over `v7.0-danctnix1`'s in-tree `drivers/staging/bes2600/`, capturing the patch groups below.
+
+Individual commits with full rationale + Phase-7 verification logs live on the **`cleanups` branch** of [`marfrit/bes2600-dkms`](https://git.reauktion.de/marfrit/bes2600-dkms/commits/branch/cleanups) — this PKGBUILD ships them squashed (one cumulative diff) for build atomicity.
 
 | group | what it does |
 |---|---|
@@ -45,7 +47,66 @@ A 16-commit cumulative diff over `v7.0-danctnix1`'s in-tree `drivers/staging/bes
 makepkg -s
 ```
 
-Identical workflow to upstream `linux-pinetab2`. Flash the resulting `.pkg.tar.zst` via `pacman -U`. Reboot to load.
+Identical workflow to upstream `linux-pinetab2`. Produces `linux-pinetab2-danctnix-besser-<ver>-aarch64.pkg.tar.zst` plus a matching `-headers` package. Build host can be aarch64 native (recommended — no cross-toolchain setup) or x86 with an aarch64 cross-compiler.
+
+Build time: ~45–55 min on an 8-core aarch64 host (boltzmann/RPi5-class), most of it the kernel modules phase.
+
+## Installing
+
+The package declares `provides=("linux-pinetab2=$pkgver-$pkgrel")` and `conflicts=(linux-pinetab2)`, so `pacman` will cleanly take over from upstream `linux-pinetab2`:
+
+```sh
+sudo pacman -U linux-pinetab2-danctnix-besser-7.0.danctnix1-1-aarch64.pkg.tar.zst
+```
+
+That removes the upstream `linux-pinetab2` package (if installed) and registers the BESser-flavored kernel under the same provides slot. Headers package is optional; install it if you build out-of-tree modules.
+
+The pacman `mkinitcpio` hook auto-generates `/boot/initramfs-linux-pinetab2-danctnix-besser.img`. Modules land in `/usr/lib/modules/<release>-pinetab2-danctnix-besser/`, vmlinuz at `/boot/vmlinuz-linux-pinetab2-danctnix-besser`, DTBs at `/boot/dtbs/rockchip/rk3566-pinetab2-{v0.1,v2.0}.dtb`.
+
+### Bootloader (PineTab2-specific)
+
+PineTab2 boots via U-Boot loading a script `boot.scr` (compiled from `/boot/boot.txt` via `mkscr`). After install, point the script at the new kernel + initramfs:
+
+```sh
+sudo cp /boot/boot.txt /boot/boot.txt.pre-besser
+sudo cp /boot/boot.scr /boot/boot.scr.pre-besser
+sudo sed -i \
+  -e 's|/vmlinuz-linux-pinetab2$|/vmlinuz-linux-pinetab2-danctnix-besser|' \
+  -e 's|/initramfs-linux-pinetab2\.img|/initramfs-linux-pinetab2-danctnix-besser.img|' \
+  /boot/boot.txt
+cd /boot && sudo ./mkscr
+sudo systemctl reboot
+```
+
+Backups (`*.pre-besser`) let you revert without touching the U-Boot console: `sudo cp /boot/boot.scr.pre-besser /boot/boot.scr` and reboot.
+
+## Verifying
+
+After reboot:
+
+```sh
+uname -r
+# expected: <kver>-pinetab2-danctnix-besser
+
+lsmod | grep -i bes2600
+# expected: bes2600 (loaded), bes2600_btuart (loaded if Bluetooth in use)
+
+cat /sys/module/bes2600/srcversion
+# expected: a srcversion distinct from the upstream linux-pinetab2 module
+```
+
+`dmesg | grep bes2600` should show clean firmware load, no SDIO TX panic, no `wsm_release_tx_buffer` WARN storm under load.
+
+## Rolling back
+
+If the new kernel misbehaves:
+
+```sh
+sudo cp /boot/boot.scr.pre-besser /boot/boot.scr
+sudo systemctl reboot
+```
+
+That returns you to whatever kernel `boot.scr` was pointing at before the install (typically upstream `linux-pinetab2` or the previous `linux-pinetab2-danctnix-besser`). The package itself can be removed with `sudo pacman -R linux-pinetab2-danctnix-besser` and the original `linux-pinetab2` re-installed via `sudo pacman -S linux-pinetab2`.
 
 ## Soft-upstream intent