64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
---
|
|
id: PLN-0090
|
|
ticket: vm-render-parallel-execution-boundary
|
|
title: Add Render Frame Pacing Contract
|
|
status: done
|
|
created: 2026-06-05
|
|
ref_decisions: [DEC-0031]
|
|
tags: [runtime, frame-clock, scheduler, vm]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0031` separates Game logical frame pacing from render worker ACK. Game frames are paced by a frame clock/scheduler and still end at `FRAME_SYNC`.
|
|
|
|
## Objective
|
|
|
|
Define and implement the runtime contract that authorizes Game logical frames without using render present completion as ACK.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0031`.
|
|
- `PLN-0091` should define which AppModes consume this policy.
|
|
|
|
## Scope
|
|
|
|
- Introduce or formalize a `FrameClock`/`FrameScheduler` authority for Game workloads.
|
|
- Ensure Game VM runs at most one logical frame per authorized frame tick.
|
|
- Preserve `FRAME_SYNC` as logical frame end.
|
|
- Record overrun/repeat conditions through telemetry hooks.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not make Shell UI run a game loop.
|
|
- Do not implement catch-up frames or logical frame skipping.
|
|
- Do not tie VM progress to render ACK.
|
|
|
|
## Execution Method
|
|
|
|
1. Inspect current tick/budget/`FRAME_SYNC` handling.
|
|
2. Identify where a frame tick should authorize Game VM execution.
|
|
3. Introduce a narrow scheduling API consumed by Game lifecycle code.
|
|
4. Preserve budget/cycle/time accounting only for watchdog, certification, and diagnostics.
|
|
5. Add telemetry points for logical-frame-overrun and no-new-frame/repeat.
|
|
6. Document the distinction between logical frame ID, produced submission ID, and presented frame ID.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Game VM cannot run unlimited logical frames ahead of the frame clock.
|
|
- Render worker or render consumer ACK is not required to start the next logical frame.
|
|
- Slow logical frames remain sequential and produce overrun/stutter telemetry.
|
|
- Shell lifecycle remains unaffected.
|
|
|
|
## Tests
|
|
|
|
- Unit tests for scheduler permitting one Game frame per tick.
|
|
- Test that no catch-up `N+k` logical frame is produced after overrun.
|
|
- Regression tests around `FRAME_SYNC` behavior.
|
|
|
|
## Affected Artifacts
|
|
|
|
- VM runtime scheduling modules.
|
|
- Firmware/Game running step.
|
|
- Telemetry interfaces touched by pacing.
|