Keep OSD and startup responsive with frontend scanout

[wizzomafizzo]

Summary

• Proxy complete scanout UIO transactions over versioned parent/child IPC instead of granting frontend direct FPGA-bus ownership. Keep slot-lifecycle and bus guards distinct; legacy handshakes fall back to fb0.
• Bound noisy-controller draining, keep proxy input polls nonblocking, and exclude active frontend from stock Menu rumble diagnostics.
• Parse command FIFO as bounded newline stream, preserving fragmented/coalesced commands.
• Restart a fallback-sized frontend when EDID arrives after the bounded watch expires, avoiding a 720p viewport on 1080p output.

Changes stay fork-owned except surgical input/video hooks; no Makefile, release-channel, or kernel changes.

Verification

GNU ARM Docker build and standalone ARM FIFO/proxy tests passed. Integration device verified visible OSD over scanout, input return after closing it, old-frontend fallback, and late EDID after 40 seconds recovering to 960x540 rendering on full 1080p. Existing controller map/configuration preserved.

Physical PS4 button latency/mapping/rumble still needs operator acceptance; rumble exclusion is defensive, not proof of the reporter's exact cause. Paired frontend required for proxy scanout; current kernel-module ABI remains unchanged.

Related frontend: ZaparooProject/zaparoo-frontend#457
Related Menu: ZaparooProject/Menu_MiSTer#5

Summary by CodeRabbit

• New Features

  • Added resilient command-stream handling for multiline, oversized, and malformed input.
  • Added scanout protocol v2 with frontend slot ownership and proxied hardware transactions.
  • Added automatic frontend restart when display information becomes available after startup.
  • Improved launcher liveness monitoring and scanout-aware input polling.

• Bug Fixes

  • Prevented framebuffer updates from interfering with active alternate-launcher scanout.
  • Improved recovery when continuous input or display handoff could stall the launcher.

• Documentation

  • Updated scanout protocol documentation, ownership behavior, packet handling, and build/test guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 2f375e7c-0a26-42f7-a495-d1a1b1efb739

📥 Commits

Reviewing files that changed from the base of the PR and between d7dc337 and a7e96b1.

📒 Files selected for processing (11)

• ZAPAROO_FORK.md
• input.cpp
• support/zaparoo/SCANOUT.md
• support/zaparoo/alt_launcher.cpp
• support/zaparoo/alt_launcher.h
• support/zaparoo/command_stream.h
• support/zaparoo/scanout.cpp
• support/zaparoo/scanout.h
• support/zaparoo/scanout_proxy.h
• support/zaparoo/tests/integration_test.cpp
• video.cpp

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds buffered FIFO command parsing and launcher input scheduling. It changes scanout ownership to protocol v2 slot leases with Main-side UIO proxying. It also adds late-EDID frontend recovery and separates scanout ownership from direct bus ownership.

Changes

Frontend liveness and scanout proxy

Layer / File(s)	Summary
FIFO command framing and input scheduling support/zaparoo/command_stream.h, input.cpp, support/zaparoo/tests/integration_test.cpp	ZaparooCommandStream frames complete FIFO lines and discards malformed or oversized lines. Menu polling yields to the alternate launcher during continuous input. Integration tests cover FIFO framing and proxy validation.
Scanout v2 packet and ownership contract support/zaparoo/scanout_proxy.h, support/zaparoo/scanout.h, support/zaparoo/SCANOUT.md	The scanout contract uses v2 slot ownership and defines packet validation for supported UIO commands. Documentation describes proxy operation and ownership predicates.
Main-side UIO proxy execution support/zaparoo/scanout.cpp	Main negotiates v2 proxy leases, validates received packets, executes SPI transfers, and returns response words. Invalid packets do not release the lease.
Launcher display ownership and recovery support/zaparoo/alt_launcher.cpp, support/zaparoo/alt_launcher.h, video.cpp, ZAPAROO_FORK.md	The launcher records spawn-time EDID, restarts eligible frontends when EDID appears late, and exposes scanout activity separately from UIO bus ownership. Framebuffer behavior uses active scanout state.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Frontend
  participant Main
  participant FPGA
  Frontend->>Main: Negotiate scanout v2 slot
  Main-->>Frontend: Grant proxy ownership
  Frontend->>Main: Send framed UIO packet
  Main->>FPGA: Execute SPI command
  FPGA-->>Main: Return word data
  Main-->>Frontend: Return updated packet

Loading

Merge Risk: ⚪ Minimal · up to a7e96

No concrete merge-blocking issue was established in the reviewed change.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 9 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: improving OSD and startup responsiveness through frontend scanout handling.

Full details: Docstring Coverage

Explanation

Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 9 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}