## 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.