Merge branch 'fix/vrr-cursor-commit': carry cursor moves on game frames under VRR

commit: d1d5df802ba7aaa6e94f5ad121fc437d88e8fb50
author: brice · 24d ago · 2026-09-28 15:39 UTC
merge of: 7b60e95 + ed0aede · diff against the first parent
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

3 files · +109 -2

M docs/performance.md +3 -0


@@ -6,6 +6,7 @@ How NeferWL keeps its CPU and memory use low, how to measure it, and the referen
6	6
7	7		- No reflection on the FFI boundary. libwayland and Vulkan are called through `purego.Syscall6/Syscall15` (fixed arity, zero allocation) and C calls back into Go through `purego.NewCallbackInts`. The Vulkan dispatch tables are generated methods; the libwayland wrapper caches resource id, version and client, and precomputes request argument counts.
8	8		- No allocation per frame or per request on the steady-state path. Frame callbacks, presentation reports, DRM flips, Vulkan submissions and surface updates reuse owner-goroutine scratch or immutable snapshots. Surface updates (one per `wl_surface.commit`) are recycled once no queued update references them.
	9	+	- Cursor rides on game frames under VRR. While a fullscreen game drives VRR, a cursor move waits for the game's next frame instead of its own commit: a cursor-only commit refreshes the panel at its slowest rate (~21 ms at 48 Hz) and delays the next game frame by as much. If the game stops drawing, the cursor still commits alone at 24 Hz.
9	10		- Default GOGC. The Go live heap is a few MB (client buffers live in shared and GPU memory), so the runtime default `GOGC=100` with a 256 MiB soft limit gives 2 collections on the tiled playback test where `GOGC=50` gave 13. `GOGC` and `GOMEMLIMIT` from the environment win.
10	11
11	12		## Guards

@@ -31,6 +32,8 @@ GODEBUG=gctrace=1 neferwl --backend=drm
31	32
32	33		`make tty` enables it on `localhost:6060` (`make tty PPROF=` disables it). `--pprof` also serves `/debug/pprof/profile` (CPU) and `/debug/pprof/trace` (scheduler and GC timeline for `go tool trace`). Escape analysis (`go build -gcflags=-m ./internal/adapters/vulkan`) shows why a value reaches the heap.
33	34
	35	+	`slow flip` log entries (flip over 20 ms) carry `frame` (false: cursor or VRR state commit) and `vrr`; `input stats` shows coalesced pointer motion and the longest wait for core.
	36	+
34	37		## Reference: 4K HDR tiled video playback
35	38
36	39		Workload: a browser playing 4K HDR video with 65 tiled subsurfaces committing every frame, DRM backend, `perf record -g` for 8 s. Percentages are the share of the process's own samples (inclusive).


@@ -6,6 +6,7 @@ How NeferWL keeps its CPU and memory use low, how to measure it, and the referen
6		6
7	- No reflection on the FFI boundary. libwayland and Vulkan are called through `purego.Syscall6/Syscall15` (fixed arity, zero allocation) and C calls back into Go through `purego.NewCallbackInts`. The Vulkan dispatch tables are generated methods; the libwayland wrapper caches resource id, version and client, and precomputes request argument counts.	7		- No reflection on the FFI boundary. libwayland and Vulkan are called through `purego.Syscall6/Syscall15` (fixed arity, zero allocation) and C calls back into Go through `purego.NewCallbackInts`. The Vulkan dispatch tables are generated methods; the libwayland wrapper caches resource id, version and client, and precomputes request argument counts.
8	- No allocation per frame or per request on the steady-state path. Frame callbacks, presentation reports, DRM flips, Vulkan submissions and surface updates reuse owner-goroutine scratch or immutable snapshots. Surface updates (one per `wl_surface.commit`) are recycled once no queued update references them.	8		- No allocation per frame or per request on the steady-state path. Frame callbacks, presentation reports, DRM flips, Vulkan submissions and surface updates reuse owner-goroutine scratch or immutable snapshots. Surface updates (one per `wl_surface.commit`) are recycled once no queued update references them.
		9	+	- Cursor rides on game frames under VRR. While a fullscreen game drives VRR, a cursor move waits for the game's next frame instead of its own commit: a cursor-only commit refreshes the panel at its slowest rate (~21 ms at 48 Hz) and delays the next game frame by as much. If the game stops drawing, the cursor still commits alone at 24 Hz.
9	- Default GOGC. The Go live heap is a few MB (client buffers live in shared and GPU memory), so the runtime default `GOGC=100` with a 256 MiB soft limit gives 2 collections on the tiled playback test where `GOGC=50` gave 13. `GOGC` and `GOMEMLIMIT` from the environment win.	10		- Default GOGC. The Go live heap is a few MB (client buffers live in shared and GPU memory), so the runtime default `GOGC=100` with a 256 MiB soft limit gives 2 collections on the tiled playback test where `GOGC=50` gave 13. `GOGC` and `GOMEMLIMIT` from the environment win.
10		11
11	## Guards	12		## Guards

@@ -31,6 +32,8 @@ GODEBUG=gctrace=1 neferwl --backend=drm
31		32
32	`make tty` enables it on `localhost:6060` (`make tty PPROF=` disables it). `--pprof` also serves `/debug/pprof/profile` (CPU) and `/debug/pprof/trace` (scheduler and GC timeline for `go tool trace`). Escape analysis (`go build -gcflags=-m ./internal/adapters/vulkan`) shows why a value reaches the heap.	33		`make tty` enables it on `localhost:6060` (`make tty PPROF=` disables it). `--pprof` also serves `/debug/pprof/profile` (CPU) and `/debug/pprof/trace` (scheduler and GC timeline for `go tool trace`). Escape analysis (`go build -gcflags=-m ./internal/adapters/vulkan`) shows why a value reaches the heap.
33		34
		35	+	`slow flip` log entries (flip over 20 ms) carry `frame` (false: cursor or VRR state commit) and `vrr`; `input stats` shows coalesced pointer motion and the longest wait for core.
		36	+
34	## Reference: 4K HDR tiled video playback	37		## Reference: 4K HDR tiled video playback
35		38
36	Workload: a browser playing 4K HDR video with 65 tiled subsurfaces committing every frame, DRM backend, `perf record -g` for 8 s. Percentages are the share of the process's own samples (inclusive).	39		Workload: a browser playing 4K HDR video with 65 tiled subsurfaces committing every frame, DRM backend, `perf record -g` for 8 s. Percentages are the share of the process's own samples (inclusive).

M internal/adapters/drm/output.go +39 -2


@@ -94,6 +94,10 @@ type Output struct {
94	94		vrrOn bool
95	95		vrrGame bool
96	96		composedSince time.Time
	97	+	// lastFrame is when the last frame was committed. cursorHeld: a cursor
	98	+	// move waits for the next frame (see cursorWaits).
	99	+	lastFrame time.Time
	100	+	cursorHeld bool
97	101		// wantOff is the latest Scene.Off: a client turned the display off.
98	102		// off: the CRTC is inactive for it. Every modeset (resume, recovery)
99	103		// follows wantOff, so a display turned off never lights up.

@@ -604,6 +608,7 @@ func (o Output) commitWith(fb uint32, fence os.File, async bool, vrr bool, f p
604	608		if !async {
605	609		o.overlayOn = ov.buf
606	610		}
	611	+	o.lastFrame, o.cursorHeld = time.Now(), false
607	612		f.frame, f.async = true, async
608	613		f.fences = dupFences(fence, ov.acquire)
609	614		o.setAsync(async)

@@ -623,10 +628,17 @@ func (o *Output) cursorRefused() bool {
623	628		func (o *Output) commitState(vrr bool) error {
624	629		req := &atomicReq{}
625	630		cur := cursorState{}
	631	+	// A move back to the applied state holds nothing.
	632	+	o.cursorHeld = false
626	633		if o.cursor != nil {
627	634		cur = o.cursor.desired()
628	635		if cur != o.cursor.applied {
629		-	o.cursor.props(req, o.crtc, cur)
	636	+	if o.cursorWaits(time.Now()) {
	637	+	o.cursorHeld = true
	638	+	cur = o.cursor.applied
	639	+	} else {
	640	+	o.cursor.props(req, o.crtc, cur)
	641	+	}
630	642		}
631	643		}
632	644		if vrr != o.vrrOn {

@@ -656,6 +668,18 @@ func (o *Output) commitState(vrr bool) error {
656	668		return nil
657	669		}
658	670
	671	+	// cursorMinInterval bounds how long a held cursor move waits for a frame.
	672	+	const cursorMinInterval = time.Second / 24
	673	+
	674	+	// cursorWaits reports whether a cursor move rides on the next frame
	675	+	// instead of its own commit. Under VRR a cursor-only commit refreshes the
	676	+	// panel at its slowest rate, which delays the game's next frame by up to
	677	+	// one such refresh. A game that stops drawing still gets the cursor at
	678	+	// cursorMinInterval.
	679	+	func (o *Output) cursorWaits(now time.Time) bool {
	680	+	return o.vrrOn && o.vrrGame && now.Sub(o.lastFrame) < cursorMinInterval
	681	+	}
	682	+
659	683		func boolValue(b bool) uint64 {
660	684		if b {
661	685		return 1

@@ -857,11 +881,14 @@ func (o *Output) Run(ctx context.Context, newRenderer func(w, h int) (ports.Rend
857	881		// guarantees a stopped/reset timer cannot deliver its old value.
858	882		retryTimer := time.NewTimer(time.Hour)
859	883		vrrTimer := time.NewTimer(time.Hour)
	884	+	cursorTimer := time.NewTimer(time.Hour)
860	885		o.frame.startTimer()
861	886		retryTimer.Stop()
862	887		vrrTimer.Stop()
	888	+	cursorTimer.Stop()
863	889		defer retryTimer.Stop()
864	890		defer vrrTimer.Stop()
	891	+	defer cursorTimer.Stop()
865	892		defer o.frame.stopTimer()
866	893		// seen is the latest content Seq per window. It is reported only while
867	894		// no frame is in flight: then the GPU has finished every frame that

@@ -898,6 +925,14 @@ func (o *Output) Run(ctx context.Context, newRenderer func(w, h int) (ports.Rend
898	925		} else {
899	926		vrrTimer.Stop()
900	927		}
	928	+	// A held cursor move commits alone if no frame comes in time.
	929	+	var cursorDue <-chan time.Time
	930	+	if enabled && o.cursorHeld && !o.frame.pendingCommit() {
	931	+	cursorTimer.Reset(max(0, cursorMinInterval-time.Since(o.lastFrame)))
	932	+	cursorDue = cursorTimer.C
	933	+	} else {
	934	+	cursorTimer.Stop()
	935	+	}
901	936		// A commit whose event never comes must not stop the output.
902	937		stuck := o.frame.wait(enabled)
903	938		stateDirty := false

@@ -920,6 +955,8 @@ func (o *Output) Run(ctx context.Context, newRenderer func(w, h int) (ports.Rend
920	955		stateDirty = true
921	956		case <-vrrOff:
922	957		stateDirty = true
	958	+	case <-cursorDue:
	959	+	stateDirty = true
923	960		case <-cursorWake:
924	961		stateDirty = true
925	962		case <-ctx.Done():

@@ -1149,7 +1186,7 @@ func (o *Output) completed(ev flipEvent, seen map[ports.WindowID]uint64) bool {
1149	1186		return false
1150	1187		}
1151	1188		if age := time.Since(start); age > 20*time.Millisecond {
1152		-	o.log.Info().Dur("flip_ms", age).Str("connector", o.conn.name).Msg("slow flip")
	1189	+	o.log.Info().Dur("flip_ms", age).Bool("frame", f.frame).Bool("vrr", o.vrrOn).Str("connector", o.conn.name).Msg("slow flip")
1153	1190		}
1154	1191		if o.cursor != nil {
1155	1192		o.cursor.landed()

 	vrrOn         bool
 	vrrGame       bool
 	composedSince time.Time
+	// lastFrame is when the last frame was committed. cursorHeld: a cursor
+	// move waits for the next frame (see cursorWaits).
+	lastFrame  time.Time
+	cursorHeld bool
 	// wantOff is the latest Scene.Off: a client turned the display off.
 	// off: the CRTC is inactive for it. Every modeset (resume, recovery)
 	// follows wantOff, so a display turned off never lights up.
 	if !async {
 		o.overlayOn = ov.buf
 	}
+	o.lastFrame, o.cursorHeld = time.Now(), false
 	f.frame, f.async = true, async
 	f.fences = dupFences(fence, ov.acquire)
 	o.setAsync(async)
 func (o *Output) commitState(vrr bool) error {
 	req := &atomicReq{}
 	cur := cursorState{}
+	// A move back to the applied state holds nothing.
+	o.cursorHeld = false
 	if o.cursor != nil {
 		cur = o.cursor.desired()
 		if cur != o.cursor.applied {
-			o.cursor.props(req, o.crtc, cur)
+			if o.cursorWaits(time.Now()) {
+				o.cursorHeld = true
+				cur = o.cursor.applied
+			} else {
+				o.cursor.props(req, o.crtc, cur)
+			}
 		}
 	}
 	if vrr != o.vrrOn {
 	return nil
 }
+// cursorMinInterval bounds how long a held cursor move waits for a frame.
+const cursorMinInterval = time.Second / 24
+// cursorWaits reports whether a cursor move rides on the next frame
+// instead of its own commit. Under VRR a cursor-only commit refreshes the
+// panel at its slowest rate, which delays the game's next frame by up to
+// one such refresh. A game that stops drawing still gets the cursor at
+// cursorMinInterval.
+func (o *Output) cursorWaits(now time.Time) bool {
+	return o.vrrOn && o.vrrGame && now.Sub(o.lastFrame) < cursorMinInterval
+}
 func boolValue(b bool) uint64 {
 	if b {
 		return 1
 	// guarantees a stopped/reset timer cannot deliver its old value.
 	retryTimer := time.NewTimer(time.Hour)
 	vrrTimer := time.NewTimer(time.Hour)
+	cursorTimer := time.NewTimer(time.Hour)
 	o.frame.startTimer()
 	retryTimer.Stop()
 	vrrTimer.Stop()
+	cursorTimer.Stop()
 	defer retryTimer.Stop()
 	defer vrrTimer.Stop()
+	defer cursorTimer.Stop()
 	defer o.frame.stopTimer()
 	// seen is the latest content Seq per window. It is reported only while
 	// no frame is in flight: then the GPU has finished every frame that
 		} else {
 			vrrTimer.Stop()
 		}
+		// A held cursor move commits alone if no frame comes in time.
+		var cursorDue <-chan time.Time
+		if enabled && o.cursorHeld && !o.frame.pendingCommit() {
+			cursorTimer.Reset(max(0, cursorMinInterval-time.Since(o.lastFrame)))
+			cursorDue = cursorTimer.C
+		} else {
+			cursorTimer.Stop()
+		}
 		// A commit whose event never comes must not stop the output.
 		stuck := o.frame.wait(enabled)
 		stateDirty := false
 			stateDirty = true
 		case <-vrrOff:
 			stateDirty = true
+		case <-cursorDue:
+			stateDirty = true
 		case <-cursorWake:
 			stateDirty = true
 		case <-ctx.Done():
 		return false
 	}
 	if age := time.Since(start); age > 20*time.Millisecond {
-		o.log.Info().Dur("flip_ms", age).Str("connector", o.conn.name).Msg("slow flip")
+		o.log.Info().Dur("flip_ms", age).Bool("frame", f.frame).Bool("vrr", o.vrrOn).Str("connector", o.conn.name).Msg("slow flip")
 	}
 	if o.cursor != nil {
 		o.cursor.landed()

M internal/adapters/drm/output_test.go +67 -0


@@ -192,6 +192,73 @@ func TestCursorCommitWaitsForEvent(t *testing.T) {
192	192		}
193	193		}
194	194
	195	+	// Under VRR with a game shown, a cursor move rides on the next frame: a
	196	+	// cursor-only commit would hold the panel for its slowest refresh. A game
	197	+	// that stops drawing still gets the cursor after cursorMinInterval.
	198	+	func TestVRRGameCursorWaitsForFrame(t *testing.T) {
	199	+	o, _, commits := testOutput(t)
	200	+	o.cursor.image = true
	201	+	o.vrrOn, o.vrrGame = true, true
	202	+	o.lastFrame = time.Now()
	203	+	o.cursor.Move(5, 5)
	204	+	if err := o.commitState(o.stateVRR()); err != nil {
	205	+	t.Fatal(err)
	206	+	}
	207	+	if len(*commits) != 0 \|\| !o.cursorHeld \|\| o.frame.pendingCommit() {
	208	+	t.Fatalf("cursor committed alone: %d commits held=%v", len(*commits), o.cursorHeld)
	209	+	}
	210	+	// The next frame carries the cursor.
	211	+	if err := o.commitFrame(70, nil, false, true, pendingFrame{}); err != nil {
	212	+	t.Fatal(err)
	213	+	}
	214	+	if v, _ := (*commits)[0].req.value(tCursor, 14); v != 5 \|\| o.cursorHeld {
	215	+	t.Fatalf("frame cursor x %d held=%v", v, o.cursorHeld)
	216	+	}
	217	+	o.completed(eventOf((*commits)[0]), map[ports.WindowID]uint64{})
	218	+	// The game stalls: the cursor commits alone after the interval.
	219	+	o.lastFrame = time.Now().Add(-cursorMinInterval)
	220	+	o.cursor.Move(8, 8)
	221	+	if err := o.commitState(o.stateVRR()); err != nil {
	222	+	t.Fatal(err)
	223	+	}
	224	+	if len(*commits) != 2 \|\| o.cursorHeld {
	225	+	t.Fatalf("stalled game: %d commits held=%v", len(*commits), o.cursorHeld)
	226	+	}
	227	+	if v, _ := (*commits)[1].req.value(tCursor, 14); v != 8 {
	228	+	t.Fatalf("cursor x %d", v)
	229	+	}
	230	+	}
	231	+
	232	+	// A held move reversed before the next frame holds nothing: the cursor
	233	+	// timer is not armed again.
	234	+	func TestHeldCursorMovedBackClearsHold(t *testing.T) {
	235	+	o, _, commits := testOutput(t)
	236	+	o.cursor.image = true
	237	+	o.vrrOn, o.vrrGame, o.lastFrame = true, true, time.Now()
	238	+	o.cursor.Move(0, 0)
	239	+	o.cursor.applied = o.cursor.desired() // on screen at (0, 0)
	240	+	o.cursor.Move(5, 5)
	241	+	if err := o.commitState(o.stateVRR()); err != nil \|\| !o.cursorHeld {
	242	+	t.Fatalf("err %v held=%v", err, o.cursorHeld)
	243	+	}
	244	+	o.cursor.Move(0, 0)
	245	+	if err := o.commitState(o.stateVRR()); err != nil \|\| o.cursorHeld \|\| len(*commits) != 0 {
	246	+	t.Fatalf("err %v held=%v commits %d", err, o.cursorHeld, len(*commits))
	247	+	}
	248	+	}
	249	+
	250	+	// Without a game, the cursor keeps its own commits.
	251	+	func TestCursorCommitsAloneWithoutGame(t *testing.T) {
	252	+	o, _, commits := testOutput(t)
	253	+	o.cursor.image = true
	254	+	o.vrrOn, o.lastFrame = true, time.Now()
	255	+	o.composedSince = time.Now()
	256	+	o.cursor.Move(5, 5)
	257	+	if err := o.commitState(o.stateVRR()); err != nil \|\| len(*commits) != 1 \|\| o.cursorHeld {
	258	+	t.Fatalf("err %v, %d commits held=%v", err, len(*commits), o.cursorHeld)
	259	+	}
	260	+	}
	261	+
195	262		func TestBusyCommitStaysPending(t *testing.T) {
196	263		o, _, _ := testOutput(t, unix.EBUSY)
197	264		err := o.commitFrame(70, nil, false, false, pendingFrame{})


@@ -192,6 +192,73 @@ func TestCursorCommitWaitsForEvent(t *testing.T) {
192	}	192		}
193	}	193		}
194		194
		195	+	// Under VRR with a game shown, a cursor move rides on the next frame: a
		196	+	// cursor-only commit would hold the panel for its slowest refresh. A game
		197	+	// that stops drawing still gets the cursor after cursorMinInterval.
		198	+	func TestVRRGameCursorWaitsForFrame(t *testing.T) {
		199	+	o, _, commits := testOutput(t)
		200	+	o.cursor.image = true
		201	+	o.vrrOn, o.vrrGame = true, true
		202	+	o.lastFrame = time.Now()
		203	+	o.cursor.Move(5, 5)
		204	+	if err := o.commitState(o.stateVRR()); err != nil {
		205	+	t.Fatal(err)
		206	+	}
		207	+	if len(*commits) != 0 \|\| !o.cursorHeld \|\| o.frame.pendingCommit() {
		208	+	t.Fatalf("cursor committed alone: %d commits held=%v", len(*commits), o.cursorHeld)
		209	+	}
		210	+	// The next frame carries the cursor.
		211	+	if err := o.commitFrame(70, nil, false, true, pendingFrame{}); err != nil {
		212	+	t.Fatal(err)
		213	+	}
		214	+	if v, _ := (*commits)[0].req.value(tCursor, 14); v != 5 \|\| o.cursorHeld {
		215	+	t.Fatalf("frame cursor x %d held=%v", v, o.cursorHeld)
		216	+	}
		217	+	o.completed(eventOf((*commits)[0]), map[ports.WindowID]uint64{})
		218	+	// The game stalls: the cursor commits alone after the interval.
		219	+	o.lastFrame = time.Now().Add(-cursorMinInterval)
		220	+	o.cursor.Move(8, 8)
		221	+	if err := o.commitState(o.stateVRR()); err != nil {
		222	+	t.Fatal(err)
		223	+	}
		224	+	if len(*commits) != 2 \|\| o.cursorHeld {
		225	+	t.Fatalf("stalled game: %d commits held=%v", len(*commits), o.cursorHeld)
		226	+	}
		227	+	if v, _ := (*commits)[1].req.value(tCursor, 14); v != 8 {
		228	+	t.Fatalf("cursor x %d", v)
		229	+	}
		230	+	}
		231	+
		232	+	// A held move reversed before the next frame holds nothing: the cursor
		233	+	// timer is not armed again.
		234	+	func TestHeldCursorMovedBackClearsHold(t *testing.T) {
		235	+	o, _, commits := testOutput(t)
		236	+	o.cursor.image = true
		237	+	o.vrrOn, o.vrrGame, o.lastFrame = true, true, time.Now()
		238	+	o.cursor.Move(0, 0)
		239	+	o.cursor.applied = o.cursor.desired() // on screen at (0, 0)
		240	+	o.cursor.Move(5, 5)
		241	+	if err := o.commitState(o.stateVRR()); err != nil \|\| !o.cursorHeld {
		242	+	t.Fatalf("err %v held=%v", err, o.cursorHeld)
		243	+	}
		244	+	o.cursor.Move(0, 0)
		245	+	if err := o.commitState(o.stateVRR()); err != nil \|\| o.cursorHeld \|\| len(*commits) != 0 {
		246	+	t.Fatalf("err %v held=%v commits %d", err, o.cursorHeld, len(*commits))
		247	+	}
		248	+	}
		249	+
		250	+	// Without a game, the cursor keeps its own commits.
		251	+	func TestCursorCommitsAloneWithoutGame(t *testing.T) {
		252	+	o, _, commits := testOutput(t)
		253	+	o.cursor.image = true
		254	+	o.vrrOn, o.lastFrame = true, time.Now()
		255	+	o.composedSince = time.Now()
		256	+	o.cursor.Move(5, 5)
		257	+	if err := o.commitState(o.stateVRR()); err != nil \|\| len(*commits) != 1 \|\| o.cursorHeld {
		258	+	t.Fatalf("err %v, %d commits held=%v", err, len(*commits), o.cursorHeld)
		259	+	}
		260	+	}
		261	+
195	func TestBusyCommitStaysPending(t *testing.T) {	262		func TestBusyCommitStaysPending(t *testing.T) {
196	o, _, _ := testOutput(t, unix.EBUSY)	263		o, _, _ := testOutput(t, unix.EBUSY)
197	err := o.commitFrame(70, nil, false, false, pendingFrame{})	264		err := o.commitFrame(70, nil, false, false, pendingFrame{})