====== Neutron — RK3588 mainline kernel campaign (boltzmann) ======

Neutron is the **kernel layer of [[volta|Project Volta]]**: an opinionated, mainline-tracking Linux kernel for the Radxa Rock 5 ITX+, built and run on **boltzmann** (the same machine = target + build host). Volta = Quark UEFI + Neutron kernel; this page is Neutron's state and decision log.

  * Branch: ''linux-rk3588-marfrit'' (forked from ''collabora/rockchip-v7.0'')
  * Gitea: ''ssh://gitea@git.reauktion.de:2222/marfrit/linux-rk3588-marfrit.git'' (repo to be created at first push)
  * Sibling kernel campaign: **Coulomb / RockHard** on ampere (CoolPi CM5 GenBook) — shares the same branch via genbook DTS commits 8/10/11/12 and the suspend/resume patch 14.
  * Started: 2026-04-29

===== Target =====

  * **Hardware:** Radxa Rock 5 ITX+ (RK3588 SoC, desktop SBC)
  * **Boot:** UEFI via edk2-rk3588 (Volta) — not u-boot
  * **OS:** BredOS (Arch Linux ARM-based), dracut initramfs (BredOS migrated off mkinitcpio)
  * **Vendor kernel as historically booted:** 6.1.75-rkr3
  * **Mainline-on-vendor pain point:** stock mainline kernels do not bring up NVMe at all on RK3588 — primary symptom Neutron exists to fix.

===== Branch state at session start (2026-04-29) =====

''linux-rk3588-marfrit'' was sitting at **v7.0-rc3-14-g3bf85944ea6c** — i.e. 14 commits ahead of v7.0-rc3, not 6 as memory had recorded. The 14th and headline patch is Markus's multi-subsystem RK3588 suspend/resume fix. ''edk2-rk3588'' is included as a dirty submodule; that is build-pipeline-normal (Volta intentionally builds firmware out of the same checkout).

Snapshot tag for rollback before any 2026-04-29 work:

<code>
linux-rk3588-marfrit-pre-2026-04-29   →   3bf85944ea6c
</code>

===== Hardware topology to remember =====

The Rock 5 ITX+ chassis labels for HDMI are **inverted vs SoC names** — easy way to wire a patch to the wrong VOP2 video port.

^ Chassis label ^ DTS label ^ SoC port ^ VOP2 video port ^ Bridge ^
| HDMI1 | ''hdmi1-con'' | native dw-hdmi-qp + hdptxphy1 | VP1 | (none — direct HDMI) |
| HDMI2 | ''hdmi0-con'' | DP1 (DisplayPort) | VP2 | radxa,ra620 simple-bridge (DP→HDMI, mainline) |

Markus runs an external HDMI→DP converter on chassis HDMI1, because the monitors only do 60 Hz on DP. That choice has consequences for which patch series matter (see decisions below).

DTS filename is ''rk3588-rock-5-itx.dts'' — **no ''-plus''** suffix. Memory previously had this wrong; corrected 2026-04-29.

===== Why this campaign exists =====

  - Vendor 6.1.75-rkr3 is a dead end for new userspace (display, video, scheduler).
  - Mainline RK3588 has matured fast under Collabora, but two things still block daily-driver use on the Rock 5 ITX+:
    * **NVMe doesn't come up at all** without out-of-tree PCIe3 PHY work.
    * **HDMI 2.0 4K@60** doesn't reliably negotiate without the SCDC scrambling series and the recent samsung-hdptx + dw-dp work.
  - Goal: a mainline-tracking branch on which boltzmann boots from NVMe, drives both 4K monitors, suspends, and resumes — and which can be rebased forward against ''collabora/rockchip-v7.0'' without merge mud.

===== Method =====

  * Cherry-pick from Collabora **as-is**, oldest-first, with ''cherry-pick -x'' so authorship is preserved and a "(cherry picked from commit …)" trail lands in each message. Reason: keep merge cleanliness with future Collabora updates and stay close to upstream-submittable shape.
  * **Phased**, not bundled. Each phase targets one symptom, rebuilds, installs additively (suffix tag), reboots, verifies. Bisectability matters — a single mass cherry-pick across PCIe + display + PHY would make any regression unbisectable.
  * **Additive install** under per-phase suffixes (''-marfrit-A1'', ''-marfrit-B'', …) into ''/boot'' and grub. Vendor kernel stays default (grub index 0). Each new kernel mirrors BredOS's existing ''-mainline'' triplet (normal / initramfs-shell / no-initramfs).
  * **One-shot watchdog** via ''grub-reboot'' (''next_entry'' in grubenv, ''boot_once=true''). On a boot-time hang, power-cycle returns to vendor automatically. No HW watchdog yet.
  * **Mailing-list scrub** before every phase: ''lists.infradead.org/pipermail/linux-rockchip/'' and the matching Collabora topic branches.

===== Phase A1 — NVMe stability (applied 2026-04-29) =====

Four commits cherry-picked from ''collabora/rockchip-v7.0'', oldest-first:

<code>
ecec5f3cf45c  phy: rockchip-snps-pcie3: Add phy_calibrate() support
a3ccaa4588ab  phy: rockchip-snps-pcie3: Increase sram init timeout
1688debd435a  phy: rockchip-snps-pcie3: Check more sram init status for RK3588
5a9704d0bcd8  phy: rockchip-snps-pcie3: Only check PHY1 status when using it
</code>

Together these address the long-standing "mainline kernel doesn't bring up NVMe at all on RK3588" failure that has kept Markus pinned to vendor 6.1.75-rkr3.

Two ''dw-rockchip'' companion commits (''f70c223c7fd3'', ''38a56c2e095a'') were **deliberately skipped**: their prerequisite ''c930b10f17c0'' ("Simplify regulator setup with ''devm_regulator_get_enable_optional()''") is not in v7.0-rc3 yet. Pulling them in without the prerequisite would either fail to apply or compile to subtly wrong runtime behaviour.

==== Build ====

  * 90 m 05 s wall, exit 0, **16245 ''.o'' files**, ''KERNELRELEASE = 7.0.0-rc3-ARCH+''.
  * Local-only, ''-j8''. **distcc was unavailable**: CT108 (aarch64crosscompiler) has been retired from data, the dcw3 daemon is down, and only ''tesla.fritz.box:3632'' was up — too few extra cores to bother spinning up a pump pipeline for.

==== Install ====

''-marfrit-A1'' suffix, three grub menuentries appended to ''/etc/grub.d/40_custom'' (normal / initramfs-shell / no-initramfs), mirroring BredOS's ''-mainline'' triplet. Vendor entry stays default (grub index 0).

==== Watchdog (one-shot) ====

<code>
sudo grub-reboot 'BredOS, with Linux 7.0.0-rc3-ARCH+ marfrit-A1'
</code>

Sets ''next_entry'' in grubenv. Grub consumes it on the next boot (''boot_once=true'') and clears it. On a hang, manual power-cycle puts us back on the vendor entry.

==== Verification (pending reboot) ====

<code>
uname -r
lsblk | grep nvme
dmesg | grep -iE 'pcie3|samsung-pcie3|nvme'
findmnt /home
</code>

If clean, run **fio mixed-RW soak ≥ 30 min** on ''/home/scratch/''. Clean soak = mark Phase A done.

===== Phase B — 4K HDMI on HDMI1 + HDMI2 (staged, not yet run) =====

Pre-built script: ''~/src/linux-rockchip/.git-phase-b-2026-04-29.sh''. It rebases the branch to drop the original patches 1+2 (samsung-hdptx rate recalc + dw-dp ''MEDIA_BUS_FMT_FIXED'') first, because those two are about to be re-applied as part of larger Collabora series:

<code>
git rebase --onto v7.0-rc3 1a61b33e881f linux-rk3588-marfrit
</code>

Then, oldest-first:

  * **B2** (6 commits) — full samsung-hdptx series from ''collabora/rockchip-v7.0''.
  * **B3** (13 commits) — full dw-dp series from ''collabora/rockchip-v7.0''.
  * **B1** (11 commits) — HDMI 2.0 SCDC scrambling + cleanups from ''collabora/cristicc/hdmi-frl''. Headline ''3b36f83b654c''. Equivalent ML series: [[https://lists.infradead.org/pipermail/linux-rockchip/2026-April/070300.html|infradead pipermail 070300–070309]].
  * **B4** (4 commits) — auxiliary HPD / encoder fixes.

==== HDMI 2.1 FRL: deliberately skipped ====

Markus's monitors only do 60 Hz on DP, and 4K@60 8 bpc fits in HDMI 2.0 TMDS at 594 MHz, which **B1's SCDC scrambling unlocks**. There is no need to pull in the FRL series for this hardware; it would only add risk surface.

==== HDMI2 needs zero driver work ====

''radxa,ra620'' is already mainline as a ''simple-bridge'' (transparent DP→HDMI). The April 28 ML series for the Lontium **LT8711UXD** is irrelevant — different bridge IC, not what this board has.

===== Conditional follow-ups =====

Stage these only if Phase A or Phase B don't fully solve their respective symptoms:

  * **Phase A2 / A3** — list-only NVMe quirks + LTSSM debug aids. Run if A1 leaves intermittent NVMe drops.
  * **Phase B5** — usbdp PHY1 stability. Run if Phase B leaves HDMI1 link-flaps.

===== Decisions worth recording =====

  - **Cherry-pick from Collabora as-is, ''-x''.** Authorship preserved, traceable to the Collabora commit, easy to drop when the same patch lands upstream.
  - **A first, B second, sequential.** A NVMe regression and a B display regression must remain bisectable independently.
  - **Vendor entry stays default in grub.** Boot-time failures revert by physics, not by us logging in.
  - **Use ''grub-reboot'' as a one-shot watchdog**, not a hardware WDT. Cheaper and reversible.
  - **No automation against the Office or Himbeere Fritz!DECT plugs** for kernel-test reboots — those plugs kill more than just boltzmann. (See HIS notes.)
  - **HDMI 2.1 FRL skipped** because the monitors top out at 60 Hz on DP. Re-evaluate when Markus's display fleet changes.

===== Cross-project ties =====

  * [[volta|Project Volta]] — UEFI / firmware umbrella that this kernel boots under.
  * [[rk3588_ddr|Project MegabitChip (rk3588_ddr)]] — RK3588 DDR init blob RE; cross-applies for any kernel that has to coexist with custom-trained DDR.
  * [[rk3588_lp5_oc|RK3588 LPDDR5 overclock]] — same vendor blob family as MegabitChip; kernel side stays unchanged.
  * [[bin|Bin (GenBook u-boot eDP)]] — sibling RK3588 display bring-up, not on this board but the VOP2 / eDP knowledge is reusable.
  * **Coulomb / RockHard** on ampere — shares ''linux-rk3588-marfrit''; genbook DTS + the suspend/resume patch ride along.
  * **[[fourier:start|Fourier]]** — HW video decode consumer. Currently runs Path B (''mpp_rkvdec2''); will switch to Path A (mainline VDEC stateless / VDPU381) once Neutron reaches 6.14+.

===== Outstanding =====

  * **User-initiated reboot** to test marfrit-A1 (LLM proxy + llamafile go down for the duration).
  * Push to gitea + create ''marfrit/linux-rk3588-marfrit'' (recipe in memory ''reference_gitea_create_repo.md'').
  * Run Phase B once A is confirmed.