bQUARKz
377cb41a3f
Some checks failed
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
150 lines
5.1 KiB
Markdown
150 lines
5.1 KiB
Markdown
# Boot Profiles
|
|
|
|
Domain: firmware boot flow
|
|
Function: normative
|
|
|
|
This chapter defines how PROMETEU chooses what to execute at startup.
|
|
|
|
## 1 Boot Target
|
|
|
|
The current firmware-side boot target concept is:
|
|
|
|
```rust
|
|
enum BootTarget {
|
|
Hub,
|
|
Cartridge { path: String, debug: bool, debug_port: u16 },
|
|
}
|
|
```
|
|
|
|
This is a firmware/host orchestration contract, not a guest-visible ABI.
|
|
|
|
The local Home games library is not a separate firmware boot target. It is host
|
|
configuration consumed by the Hub profile after boot.
|
|
|
|
## 2 Boot Modes
|
|
|
|
### Hub
|
|
|
|
When the boot target is `Hub`:
|
|
|
|
- firmware boots into the Hub flow;
|
|
- no cartridge is auto-launched.
|
|
|
|
If the host also provides `--games-root <dir>`, the Hub may discover and render
|
|
valid Game cartridges from that root. Selecting one is a system-owned Home
|
|
action that requests cartridge loading after the Hub is already running.
|
|
|
|
### Cartridge
|
|
|
|
When the boot target is `Cartridge`:
|
|
|
|
1. firmware loads the requested cartridge;
|
|
2. cartridge metadata is read;
|
|
3. launch behavior follows cartridge `app_mode`;
|
|
4. bytecode execution starts through the cartridge boot protocol defined by the cartridge contract, not by textual entry metadata.
|
|
|
|
## 3 Launch Resolution by App Mode
|
|
|
|
For a cartridge boot target:
|
|
|
|
- `Game` cartridges transition into the game-running pipeline;
|
|
- `System` cartridges transition into a Runtime/Hub pipeline dedicated to
|
|
system UI and app hosting.
|
|
|
|
This preserves the distinction between machine firmware state and app execution mode.
|
|
|
|
The `System` route must not be treated as the game pipeline running inside a
|
|
window. It is a separate runtime profile path oriented around Hub ownership and
|
|
WindowManager integration. The initial implementation may be minimal, but the
|
|
routing boundary is normative: `System` does not enter `GameRunning` as its
|
|
profile pipeline.
|
|
|
|
## 4 Host CLI Relationship
|
|
|
|
Typical host-facing boot intents are:
|
|
|
|
- default start -> enter Hub;
|
|
- run cartridge -> boot with cartridge target;
|
|
- debug cartridge -> boot with cartridge target plus debug mode parameters.
|
|
- games-root start -> enter Hub with a local Game library for Home.
|
|
|
|
The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
|
|
|
|
Host CLI, debugger, and equivalent single-game launch flows are the supported
|
|
direct cartridge boot surfaces. Direct boot is not requested by guest bytecode
|
|
through a `system.run_cart` syscall or any other app-callable cartridge boot
|
|
ABI.
|
|
|
|
`--run <cart>` and `--debug <cart>` are direct cartridge boot profiles. They
|
|
select one cartridge before normal Hub/Home interaction and remain independent
|
|
from the local library.
|
|
|
|
`--games-root <dir>` is a Hub/Home library configuration. It does not
|
|
auto-launch a cartridge and does not create a guest-visible launch API.
|
|
|
|
The v1 games root contract is:
|
|
|
|
- the root contains directory cartridges as immediate child directories;
|
|
- recursive discovery is not performed;
|
|
- only valid cartridges whose manifest declares `app_mode: "Game"` are listed;
|
|
- Shell/System apps, packaged `.pmc` cartridges, remote catalogs, marketplace
|
|
metadata, search, icons, and rich presentation are outside this profile;
|
|
- invalid candidates are logged and omitted from the Home list;
|
|
- Home entries may display only `title`, `app_id`, and `app_version`;
|
|
- selecting a Home entry requests firmware/SystemOS loading for that cartridge
|
|
and transitions through `LoadCartridge`;
|
|
- launch failure leaves or returns the machine to Home and records an error.
|
|
|
|
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.
|
|
|
|
## 5 Firmware State Relationship
|
|
|
|
Boot target selection feeds into firmware states such as:
|
|
|
|
- `Reset`
|
|
- `SplashScreen`
|
|
- `LaunchHub`
|
|
- `HubHome`
|
|
- `LoadCartridge`
|
|
- `GameRunning`
|
|
- `AppCrashes`
|
|
|
|
Additional firmware states may represent dedicated `System` profile execution.
|
|
Such states are part of the Runtime/Hub route and do not change the `Game`
|
|
pipeline contract.
|
|
|
|
Boot target is not itself a firmware state. It is an input to the firmware state machine.
|
|
|
|
## 6 Debug Boot
|
|
|
|
When booting a cartridge in debug mode:
|
|
|
|
- firmware/runtime uses the cartridge target path;
|
|
- debugger-related startup behavior is enabled;
|
|
- execution still follows the same cartridge/app-mode resolution path.
|
|
|
|
Debug mode changes orchestration, not the cartridge contract.
|
|
|
|
## 7 Smoke Validation
|
|
|
|
The local Home library path should be smoke tested in release mode for realistic
|
|
interactive speed:
|
|
|
|
```sh
|
|
cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges
|
|
```
|
|
|
|
Direct single-cartridge boot remains a separate validation path:
|
|
|
|
```sh
|
|
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
|
|
```
|
|
|
|
## 8 Relationship to Other Specs
|
|
|
|
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
|
|
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure.
|
|
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines the observability/debugging layer.
|