implements PLN-0138
This commit is contained in:
@@ -239,8 +239,10 @@ The same physical surface may be reused by multiple visual owners, but logical
|
||||
ownership MUST remain explicit.
|
||||
|
||||
Game pause/resume, foreground stack behavior, and coexistence of a paused Game
|
||||
with VM-backed Shell apps are outside this contract and are tracked by the
|
||||
foreground/lifecycle discussion.
|
||||
with VM-backed Shell apps are defined by the foreground/lifecycle contract. The
|
||||
render boundary's responsibility is narrower: foreground owner changes MUST
|
||||
advance ownership, stale submissions MUST be discarded, and visual return to a
|
||||
resumed Game MUST wait for a valid submission from the current ownership epoch.
|
||||
|
||||
### 4.7 Render telemetry
|
||||
|
||||
|
||||
@@ -107,3 +107,21 @@ Input access is VM-owned and should not be reported as host syscall consumption.
|
||||
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
||||
|
||||
Platform differences in physical device mapping are resolved outside VM semantics.
|
||||
|
||||
## 9 Host/System Controls
|
||||
|
||||
Host/System controls are not part of the guest-visible input surface.
|
||||
|
||||
The Home/SystemOS request changes machine foreground authority. It must be
|
||||
handled by the host, firmware, or SystemOS before input is exposed to the Game.
|
||||
It must not be represented as `pad.start`, `pad.select`, a new pad field, a VM
|
||||
intrinsic, or a userland syscall.
|
||||
|
||||
For the desktop host, `Esc` is the primary keyboard mapping for the
|
||||
Home/SystemOS request. The physical `Home` key may be supported as an alias.
|
||||
Both mappings are host controls and must not mutate `InputSignals`.
|
||||
|
||||
When a Game leaves or re-enters foreground, pending Game input must be cleared
|
||||
or barriered so held or pressed input cannot leak across pause/resume
|
||||
boundaries. This barrier applies to the Game-facing snapshot; it does not
|
||||
change the meaning of host/system Home controls.
|
||||
|
||||
@@ -100,7 +100,40 @@ Important properties:
|
||||
- no execution occurs outside the frame loop;
|
||||
- frame structure remains observable for host tooling and host-owned certification.
|
||||
|
||||
## 7 Render Worker Concurrency
|
||||
## 7 Foreground Lifecycle Events
|
||||
|
||||
Foreground lifecycle events are system events with bounded delivery points.
|
||||
They do not execute arbitrary guest callbacks at arrival time.
|
||||
|
||||
The Game pause path is:
|
||||
|
||||
```text
|
||||
Home/SystemOS request
|
||||
-> pause event becomes visible to the Game
|
||||
-> bounded pause reaction budget
|
||||
-> SystemOS suspension, even if the Game did not cooperate
|
||||
```
|
||||
|
||||
The Game resume path is:
|
||||
|
||||
```text
|
||||
SystemOS resume request
|
||||
-> VM reactivation
|
||||
-> resume or foreground-restore event becomes visible to the Game
|
||||
-> Game may synchronize while still internally paused
|
||||
-> visual foreground returns after a valid current-epoch render submission
|
||||
```
|
||||
|
||||
`Paused` is the Game-visible event/state. `Suspended` is the OS-owned
|
||||
scheduler/runtime state. A Game may observe pause/resume, but it must not
|
||||
control whether SystemOS suspends or resumes the VM.
|
||||
|
||||
Pause budgets are measured in deterministic machine units, not host wall-clock
|
||||
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
|
||||
and no frame pacing. Real background execution is outside the v1 foreground
|
||||
contract.
|
||||
|
||||
## 8 Render Worker Concurrency
|
||||
|
||||
The render worker is not a machine-visible event source and does not introduce
|
||||
guest callbacks. It is an implementation-side consumer of closed render
|
||||
@@ -127,7 +160,7 @@ Shutdown is explicit and bounded. A shutdown request wakes a waiting worker,
|
||||
causes pending work that will not be consumed to be discarded, and reports a
|
||||
typed failure if the worker cannot join within the configured timeout.
|
||||
|
||||
## 8 Async Asset and IO Work Lane
|
||||
## 9 Async Asset and IO Work Lane
|
||||
|
||||
The asset/IO async work lane is not a machine-visible event source and does not
|
||||
introduce guest callbacks. It is an implementation-side lane for asset
|
||||
@@ -151,7 +184,7 @@ does not publish resident graphics/audio/scene state directly.
|
||||
FS and game persistence services may consume this lane for IO-style work, but
|
||||
public FS API shape is defined by the FS/app-home contract, not by this chapter.
|
||||
|
||||
## 9 Determinism and Best Practices
|
||||
## 10 Determinism and Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
@@ -166,7 +199,7 @@ PROMETEU discourages:
|
||||
- hidden timing channels;
|
||||
- ambiguous out-of-band execution.
|
||||
|
||||
## 10 Relationship to Other Specs
|
||||
## 11 Relationship to Other Specs
|
||||
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
|
||||
|
||||
@@ -43,6 +43,13 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
Game directory cartridges.
|
||||
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
|
||||
discovered cartridge.
|
||||
- **Foreground visual owner**: the single machine owner whose visual output may
|
||||
be presented at a given time.
|
||||
- **Paused**: a Game-visible lifecycle event/state. The Game may observe it and
|
||||
prepare for foreground loss.
|
||||
- **Suspended**: an OS-owned scheduler/runtime state. A suspended Game remains
|
||||
resident but does not receive normal gameplay ticks, normal Game input, or
|
||||
frame pacing.
|
||||
|
||||
## 3 POS Responsibilities
|
||||
|
||||
@@ -154,7 +161,50 @@ Shell task loses its eligible focused window
|
||||
-> FirmwareState::HubHome
|
||||
```
|
||||
|
||||
## 7 Cartridge Load Flow
|
||||
## 7 Foreground Stack and Game Pause
|
||||
|
||||
The v1 foreground contract is single-owner:
|
||||
|
||||
- exactly one foreground visual owner exists at a time;
|
||||
- at most one Game may be resident;
|
||||
- at most one Shell app may be foreground;
|
||||
- Hub/Home is the root Shell owner and back-stack controller.
|
||||
|
||||
The minimal supported navigation cycle is:
|
||||
|
||||
```text
|
||||
Game foreground
|
||||
-> Home request
|
||||
-> Game pause notification
|
||||
-> Game suspended by SystemOS after a bounded budget
|
||||
-> Hub/Home foreground
|
||||
-> optional Shell foreground
|
||||
-> Shell close returns to Hub/Home
|
||||
-> same Game resume/foreground-restore notification
|
||||
-> Game foreground after a valid current-epoch render submission
|
||||
```
|
||||
|
||||
`Paused` is cooperative and visible to the Game. `Suspended` is imposed by
|
||||
SystemOS. The Game may react to pause/resume, but it must not control whether
|
||||
the OS suspends or resumes its VM.
|
||||
|
||||
When Home is requested during Game execution, SystemOS must notify the Game and
|
||||
grant a short bounded pause budget. After the budget, SystemOS may suspend the
|
||||
VM even if the Game did not cooperate. While suspended, the Game must not
|
||||
receive normal gameplay ticks, normal Game input, or frame pacing.
|
||||
|
||||
When returning to the same Game, SystemOS must reactivate the VM and send a
|
||||
resume or foreground-restore notification before visual foreground is restored.
|
||||
The Game may remain internally paused while it synchronizes. Hub/Shell remains
|
||||
visible until the resumed Game publishes a valid render submission for the
|
||||
current ownership epoch.
|
||||
|
||||
Input pending for the Game must be cleared or barriered across pause/resume
|
||||
boundaries. Game audio pauses with the Game VM in v1. Independent background
|
||||
audio, real background execution, multiple resident Games, multiple foreground
|
||||
Shells, and direct Game-to-Game switching are outside this contract.
|
||||
|
||||
## 8 Cartridge Load Flow
|
||||
|
||||
Current high-level flow:
|
||||
|
||||
@@ -179,7 +229,7 @@ If the selected cartridge cannot be loaded, firmware must leave or return the
|
||||
machine in the Hub/Home flow and record the failure through diagnostics or
|
||||
logging. A polished Home error surface is not required by v1.
|
||||
|
||||
## 8 Firmware States
|
||||
## 9 Firmware States
|
||||
|
||||
The current firmware state model includes:
|
||||
|
||||
@@ -193,7 +243,7 @@ The current firmware state model includes:
|
||||
|
||||
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
|
||||
|
||||
## 9 Execution Contract
|
||||
## 10 Execution Contract
|
||||
|
||||
For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
@@ -204,7 +254,7 @@ For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
This keeps the machine model deterministic and observable.
|
||||
|
||||
## 10 Crash Handling
|
||||
## 11 Crash Handling
|
||||
|
||||
Firmware owns terminal fault presentation.
|
||||
|
||||
@@ -216,7 +266,7 @@ When a terminal app fault occurs:
|
||||
|
||||
Crash handling is outside the guest VM execution model.
|
||||
|
||||
## 11 Relationship to Other Specs
|
||||
## 12 Relationship to Other Specs
|
||||
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
|
||||
|
||||
@@ -99,6 +99,11 @@ Game-to-game switching after a game is already active is not part of this boot
|
||||
profile. That orchestration belongs to the foreground/home and cartridge switch
|
||||
contracts.
|
||||
|
||||
The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
|
||||
Game is already running. It does not change direct `--run`, debugger direct
|
||||
boot, or `--games-root` Home library startup semantics. Home/SystemOS requests
|
||||
are host/system controls, not guest cartridge boot APIs.
|
||||
|
||||
## 5 Firmware State Relationship
|
||||
|
||||
Boot target selection feeds into firmware states such as:
|
||||
|
||||
Reference in New Issue
Block a user