besser/danctnix-besser-pkgbuild/README.md

# linux-pinetab2-danctnix-besser

Soft-upstream fork of `linux-pinetab2` (DanctNIX kernel for PineTab2) carrying the **BESser** bes2600 staging-driver patchset.

Drop-in replacement for `linux-pinetab2`. Same kernel version, same config, same modules — only the `drivers/staging/bes2600/` driver differs.

## What's in the patchset

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 |
|---|---|
| **c-stack (Patches A, B, c5.1–c5.2.1, c6.1, c6.2, c7)** | wifi-stability fixes: decrypt-storm fast-recover, connection-loss bus-reset, scan-defer-on-firmware-reject, PM state resync, firmware-doesn't-honour-PSM self-detect, multi-function SDIO `mmc_hw_reset` rescan |
| **Patch F** | cw1200 mainline backports: hw_scan SKB-lifecycle UAF, init_common destroy_workqueue on error, `atomic_add(1, x) → atomic_inc(x)` cosmetic |
| **Patch C v3** | structural: drop `sdio_rx_work` workqueue relay; IRQ → bh-direct architecture (matches mainline cw1200) |
| **Patch G** | GPL-2.0 §1 attribution restoration: SPDX-License-Identifier on every file, Tarnyagin/ST-Ericsson Copyright restored on cw1200-derived files |
| **Patch D** | `ba_lock` removed; `ba_acc/ba_cnt/ba_acc_rx/ba_cnt_rx/ba_ena` converted to `atomic_t`; per-RX-frame spinlock eliminated |
| **Patch E** | per-RX-frame `ps_state_lock` skipped when c7's `pm_unsupported` latch is on (steady-state on production firmware) |
| **Patch C2** | `ieee80211_rx_irqsafe → ieee80211_rx_ni` at all 6 sites (kernel.org-clean process-context API; tasklet hop removed) |
| **Patch H** | bh.c hygiene cleanup: 76-line + 468-line `#if 0` cw1200-ancestor fossil blocks removed; `__bes2600_irq_enable` stub removed; per-iteration `BUG_ON` → `WARN_ON_ONCE` |

## Measured outcome (Mobian-flavor verification, expected to carry over)

- Phase 7 N=3 stress @ 4 MB/s sender on RK3566/PineTab2:
  - Patch B baseline: 1.36 MB/s
  - Patch C v3 + F + G + D + E + C2 + H: 2.28 MB/s sustained, **+67% over baseline**
- Race-fix verified under stress (no `wsm_release_tx_buffer` WARN storm under load)
- Module loads + associates cleanly; `pm_unsupported` latch fires on boot as expected
- Build clean with no warnings, srcversion `99052D7…` (Mobian-flavor) / TBD on first danctnix build

## Provenance

- Mobian-flavor source-of-truth: <https://git.reauktion.de/marfrit/bes2600-dkms> (cleanups branch)
- Per-patch breakdown + Phase 7 results: <https://git.reauktion.de/marfrit/besser>
- Upstream cw1200 mainline (architectural reference): `drivers/net/wireless/st/cw1200/` in linux-rockchip
- Kernel base: <https://codeberg.org/DanctNIX/linux-pinetab2> tag `v7.0-danctnix1`

## Why it's "BESser"

"Besser" = German for "better." Patch series ID across both DKMS (Mobian) and in-tree (Danctnix) trees. Single source-of-truth lives in `marfrit/bes2600-dkms`; this PKGBUILD is the danctnix-flavor consumption surface.

## Building

```sh
makepkg -s
```

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

Submitting this PKGBUILD to DanctNIX for review. If accepted as a replacement for `linux-pinetab2` (or sidegrade), the BESser patchset ships to all PineTab2 users via the regular danctnix package update channel. The bes2600 driver gets:

- ~2× sustained RX throughput
- Race-correctness on the hot path
- GPL-2.0 §1 attribution compliance
- Modern kernel API (no deprecated `from_timer`, no `_irqsafe` from process context, no `BUG_ON` in steady-state)

Drop-in compatibility: same kernel version, same module names, no userspace ABI change.

## Maintenance plan

- New danctnix kernel release → rebase BESser patch onto the new tag, regenerate cumulative diff, bump pkgver
- New BESser patch on Mobian DKMS → re-overlay + re-flavor + regenerate cumulative diff
- Both flavors continue to be maintained in lockstep via `marfrit/bes2600-dkms` source-of-truth

## Known gaps

- Single cumulative diff (squashed 16 commits) for now. Per-patch series can be regenerated if danctnix maintainers prefer.
- Bluetooth-side `bes2600_btuart` is independent and untouched by this patchset.
- `bes2600_switch_bt` orchestration removed (Mobian-only entry point; not used in danctnix tree).

## Author

Markus Fritsche <fritsche.markus@gmail.com>

Built collaboratively with Claude Opus 4.7 (1M context).