From 777acf7503cc882bbde043b0d233bb509fc0cece Mon Sep 17 00:00:00 2001 From: Andreas Schaafsma Date: Thu, 3 Sep 2026 06:43:34 +0200 Subject: [PATCH] plan --- AGENTS.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f6360ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,102 @@ +## CODE GENERATION INSTRUCTIONS + +You are tasked with integrating patches into my kernel to make the tearing protocol work on Wayland with my intel B580. + +## THINGS TO DO: + +Plan out how you're going to do the following. I will inspect your plan and then authorize it. + +- Custom build this MR: https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3797 + +- Fix KDE tearing on Intel Graphics using kernel patches for libdrm. Use these resources to research: + - https://bugs.kde.org/show_bug.cgi?id=520549 + - https://gitlab.freedesktop.org/drm/xe/kernel/-/work_items/8597#note_3567675 + - https://gitlab.freedesktop.org/drm/i915/kernel/-/work_items/13834 (this one has patches that supposedly fix the problem.) + + +# Plan here: + +- [ ] 1. Record the current package and kernel baselines. + - Evaluate the locked versions of Mutter, GNOME Shell, libdrm, and the selected CachyOS kernel. + - Confirm that the Intel Arc B580 (`8086:e20b`) is using the `xe` driver. + - Save the current working kernel and NixOS generation as the rollback baseline. + +- [ ] 2. Pin all experimental upstream sources. + - Pin Mutter merge request !3797 to a specific commit instead of following its branch. + - Record the MR base commit and verify whether it is compatible with the Mutter version in the locked nixpkgs input. + - Identify the exact revisions of the Intel async-flip and `IN_FORMATS_ASYNC` kernel patches referenced by the i915 and Xe work items. + - Use fixed-output hashes for every fetched patch or source archive. + +- [ ] 3. Determine which Intel DRM patches are still required. + - Inspect the selected CachyOS kernel source for patches that have already been merged or backported. + - Select only the missing patches needed to expose async-capable formats and prevent unchanged or disabled planes from incorrectly rejecting an async atomic commit. + - Confirm that the selected changes affect the Intel display code shared by `xe` and `i915`, and therefore apply to the B580 even when the original report is filed under i915. + - Document the required patch order and each patch's upstream URL and revision. + +- [ ] 4. Add a dedicated, reversible Wayland-tearing overlay or module. + - Keep the experimental Mutter and kernel overrides together in a new, clearly named repository file. + - Scope the override to `drivebystation-nix` where practical. + - Provide a single enable switch or isolated import so the experiment can be disabled without editing generated hardware configuration. + - Preserve all unrelated existing worktree changes. + +- [ ] 5. Override Mutter with merge request !3797. + - Prefer applying the pinned MR commits to the nixpkgs Mutter derivation so nixpkgs build flags and dependency wiring are retained. + - If the patch series is incompatible, use the pinned MR source only after confirming its Mutter ABI matches the installed GNOME Shell. + - Verify that libdrm is at least version 2.4.120. + - Ensure GNOME Shell and the display-manager session reference the overridden Mutter rather than merely installing it alongside the stock package. + - Enable the experimental feature with `MUTTER_DEBUG_EXPERIMENTAL_FEATURES=tearing` in the session environment. + +- [ ] 6. Override the CachyOS kernel with the selected Intel DRM patches. + - Extend the existing `pkgs.cachyosKernels.linuxPackages-cachyos-latest` kernel derivation rather than replacing it with an unrelated kernel package set. + - Apply the pinned patches in their upstream dependency order. + - Verify that every patch applies cleanly to the exact CachyOS kernel source. + - Keep `boot.extraModulePackages` tied to the patched kernel package set so `r8125` and `v4l2loopback` are rebuilt against the correct kernel. + - Do not modify the generated `hardware-configuration.nix` beyond any unavoidable existing kernel selection; place the override in a maintained host module. + +- [ ] 7. Validate the Nix expressions without activating the system. + - Run formatting and syntax checks on every changed Nix file. + - Evaluate the complete `drivebystation-nix` configuration. + - Run `nix flake check` and resolve evaluation failures attributable to these changes. + - Confirm that all sources are pinned and reproducible and that no mutable branch names remain. + +- [ ] 8. Build each risky component independently. + - Build the overridden Mutter derivation. + - Build the patched kernel derivation. + - Build the matching `r8125` and `v4l2loopback` modules. + - Inspect the build logs for rejected patches, warnings related to async flips, and ABI mismatches. + +- [ ] 9. Build the complete NixOS system before switching. + - Build the `drivebystation-nix` toplevel without activating it. + - Verify that the closure contains the pinned patched Mutter and patched CachyOS kernel. + - Confirm that a previous known-good boot generation remains available. + +- [ ] 10. Activate the result safely. + - Use `nixos-rebuild boot` first so the new system is selected only after reboot. + - Reboot into the patched generation and verify the running kernel version and `xe` driver binding. + - If the display fails or the system is unstable, boot the previous generation and disable the experimental module. + +- [ ] 11. Verify the kernel DRM capabilities. + - Run `drm_info` and confirm atomic async-page-flip capability is reported. + - Confirm `IN_FORMATS_ASYNC` is populated for supported primary planes. + - Confirm its absence on the cursor plane is handled as expected rather than causing the entire commit to fail. + - Capture a DRM debug log while submitting tearing-enabled fullscreen frames. + +- [ ] 12. Test KDE Plasma tearing. + - Enable Plasma's "Allow in fullscreen windows" tearing setting. + - Run a fullscreen tearing-aware game or test client with frame rate above the monitor refresh rate. + - Confirm that KWin's async atomic commits no longer fail with `-EINVAL`. + - Confirm that the previous `cursor A: async flip not supported` and `plane 2A: async flip not supported` errors no longer occur for disabled or unchanged planes. + - Check cursor movement, fullscreen entry and exit, direct scanout, VRR enabled and disabled, and all connected monitors. + +- [ ] 13. Test GNOME Mutter tearing. + - Start a GNOME Wayland session and confirm the tearing-control protocol is advertised. + - Run `weston-simple-egl -v -f -t` or an equivalent tearing-aware client. + - Confirm that requested asynchronous flips are accepted and visibly tear when the frame rate exceeds the refresh rate. + - Confirm unsupported async commits fall back to synchronized presentation without breaking the session. + - Test cursor movement, fullscreen transitions, VRR, multiple monitors, and suspend/resume. + +- [ ] 14. Document results and removal criteria. + - Record the tested hardware, kernel, Mutter, GNOME Shell, Plasma, and libdrm versions. + - Record the exact patches used and the outcome of both compositor tests. + - Document how to disable the overrides and roll back to the previous generation. + - Note which upstream merge or kernel release will allow each local override to be removed.