[PERF] Runtime Introspection Syscalls
This commit is contained in:
@@ -98,7 +98,7 @@ Important properties:
|
||||
|
||||
- events are processed at known points;
|
||||
- no execution occurs outside the frame loop;
|
||||
- frame structure remains observable for tooling and certification.
|
||||
- frame structure remains observable for host tooling and host-owned certification.
|
||||
|
||||
## 7 Determinism and Best Practices
|
||||
|
||||
|
||||
@@ -7,19 +7,18 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the machine-visible debugging, inspection, and profiling surface of PROMETEU.
|
||||
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`.
|
||||
|
||||
`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface.
|
||||
|
||||
It covers:
|
||||
|
||||
- execution modes;
|
||||
- pause and stepping;
|
||||
- state inspection;
|
||||
- graphics inspection;
|
||||
- runtime-visible execution control used by host tooling;
|
||||
- bounded operational telemetry;
|
||||
- profiling;
|
||||
- breakpoints and watchpoints;
|
||||
- event and fault visibility;
|
||||
- certification-facing diagnostics;
|
||||
- Host-side debug overlay (HUD) isolation.
|
||||
- certification input data;
|
||||
- host-side debug overlay (HUD) isolation.
|
||||
|
||||
## 2 Execution Modes
|
||||
|
||||
@@ -34,18 +33,18 @@ PROMETEU operates in three main modes:
|
||||
### 2.2 Debug Mode
|
||||
|
||||
- controlled execution
|
||||
- access to internal state
|
||||
- host-mediated access to internal state
|
||||
- pauses and stepping
|
||||
|
||||
### 2.3 Certification Mode
|
||||
|
||||
- deterministic execution
|
||||
- collected metrics
|
||||
- report generation
|
||||
- host-generated report output
|
||||
|
||||
No mode alters the logical result of the program.
|
||||
|
||||
## 3 Execution Debug
|
||||
## 3 Execution Control
|
||||
|
||||
### 3.1 Pause and Resume
|
||||
|
||||
@@ -64,24 +63,26 @@ During pause:
|
||||
|
||||
### 3.2 Step-by-Step
|
||||
|
||||
PROMETEU allows stepping at different levels:
|
||||
PROMETEU allows host tooling to step execution at different levels:
|
||||
|
||||
- **by frame**
|
||||
- **by function**
|
||||
- **by VM instruction**
|
||||
|
||||
Stepping by instruction reveals:
|
||||
When the host activates instruction-level inspection, it may observe:
|
||||
|
||||
- Program Counter (PC)
|
||||
- current instruction
|
||||
- operand stack
|
||||
- call stack
|
||||
|
||||
## 4 State Inspection
|
||||
## 4 State Inspection Boundary
|
||||
|
||||
Detailed state inspection is a host-owned concern. The runtime may expose deterministic machine state to host tooling, but this chapter does not define a general guest ABI for introspection convenience.
|
||||
|
||||
### 4.1 Stacks
|
||||
|
||||
PROMETEU allows inspecting:
|
||||
Host tooling may inspect:
|
||||
|
||||
- **Operand Stack**
|
||||
- **Call Stack**
|
||||
@@ -94,7 +95,7 @@ For each frame:
|
||||
|
||||
### 4.2 Heap
|
||||
|
||||
The heap can be inspected in real time:
|
||||
The host may inspect heap state in real time:
|
||||
|
||||
- total size
|
||||
- current usage
|
||||
@@ -109,22 +110,22 @@ The programmer can observe:
|
||||
|
||||
### 4.3 Global Space
|
||||
|
||||
Global variables:
|
||||
Host-owned inspection may observe global variables, including:
|
||||
|
||||
- current values
|
||||
- references
|
||||
- initialization
|
||||
|
||||
## 5 Graphics Debug
|
||||
## 5 Graphics Inspection Boundary
|
||||
|
||||
PROMETEU allows inspecting the graphics system:
|
||||
Host tooling may inspect the graphics system:
|
||||
|
||||
- front buffer
|
||||
- back buffer
|
||||
- palette state
|
||||
- active sprites
|
||||
|
||||
It is possible to:
|
||||
The host may:
|
||||
|
||||
- freeze the image
|
||||
- observe buffers separately
|
||||
@@ -153,7 +154,7 @@ SYSTEM:612
|
||||
|
||||
### 6.2 Per-Function Profiling
|
||||
|
||||
PROMETEU can associate cycles with:
|
||||
Host tooling may associate cycles with:
|
||||
|
||||
- functions
|
||||
- methods
|
||||
@@ -161,7 +162,7 @@ PROMETEU can associate cycles with:
|
||||
|
||||
### 6.3 Per-Instruction Profiling
|
||||
|
||||
At the lowest level, the system can display:
|
||||
At the lowest level, host tooling can display:
|
||||
|
||||
- executed instructions
|
||||
- individual cost
|
||||
@@ -185,13 +186,13 @@ Peak:34KB❌
|
||||
Limit:32KB
|
||||
```
|
||||
|
||||
These data directly feed the certification.
|
||||
These data feed host-owned certification.
|
||||
|
||||
### 7.1 Bank Occupancy Profiling
|
||||
|
||||
Bank occupancy diagnostics are slot-first.
|
||||
|
||||
The visible per-bank telemetry used by host inspection surfaces and certification is:
|
||||
The visible per-bank telemetry used by host inspection surfaces and host-owned certification is:
|
||||
|
||||
- `bank_type`
|
||||
- `used_slots`
|
||||
@@ -206,9 +207,11 @@ Byte-oriented bank occupancy is not the canonical visible profiling contract.
|
||||
|
||||
## 8 Breakpoints and Watchpoints
|
||||
|
||||
Breakpoints and watchpoints are host-mediated tooling controls. They are not part of the gameplay-facing cartridge contract.
|
||||
|
||||
### 8.1 Breakpoints
|
||||
|
||||
PROMETEU supports breakpoints in:
|
||||
The platform supports host-owned breakpoints in:
|
||||
|
||||
- specific frames
|
||||
- functions
|
||||
@@ -222,7 +225,7 @@ Breakpoints:
|
||||
|
||||
### 8.2 Watchpoints
|
||||
|
||||
Watchpoints monitor:
|
||||
Host tooling may monitor watchpoints over:
|
||||
|
||||
- variables
|
||||
- heap addresses
|
||||
@@ -233,10 +236,14 @@ Execution can pause when:
|
||||
- a value changes
|
||||
- a limit is exceeded
|
||||
|
||||
## 9 Event and Fault Debugging
|
||||
## 9 Event and Fault Diagnostics
|
||||
|
||||
## 10 Certification Diagnostics
|
||||
|
||||
Certification diagnostics are produced by the host from deterministic runtime telemetry.
|
||||
|
||||
The runtime does not generate the final certification artifact. It only maintains the machine-facing counters and summaries required for host-owned certification.
|
||||
|
||||
Certification diagnostics may enforce bank occupancy ceilings.
|
||||
|
||||
For bank residency, certification uses slot-based limits, such as:
|
||||
@@ -246,7 +253,7 @@ For bank residency, certification uses slot-based limits, such as:
|
||||
|
||||
Bank certification MUST NOT depend on `max_gfx_bytes` or `max_audio_bytes`.
|
||||
|
||||
PROMETEU allows observing:
|
||||
Host tooling may observe:
|
||||
|
||||
- event queue
|
||||
- active timers
|
||||
@@ -259,7 +266,7 @@ Each event has:
|
||||
- cost
|
||||
- consequence
|
||||
|
||||
## 10 Host-Side Debug Overlay (HUD) Isolation
|
||||
## 11 Host-Side Debug Overlay (HUD) Isolation
|
||||
|
||||
The visual Debug Overlay (HUD) for technical inspection is not part of the emulated machine pipeline.
|
||||
|
||||
@@ -270,7 +277,7 @@ The visual Debug Overlay (HUD) for technical inspection is not part of the emula
|
||||
3. **Host overlay module:** The Desktop Host owns a dedicated overlay module that performs host-side text, panel, and simple bar composition.
|
||||
4. **Composition boundary:** The overlay is composed on the Host presentation surface after the emulated frame is ready. Overlay pixels must not be written back into the emulated framebuffer.
|
||||
5. **Host control:** Overlay visibility and presentation policy remain under Host control.
|
||||
2. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
|
||||
6. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer.
|
||||
|
||||
### 10.2 Principles
|
||||
|
||||
@@ -287,11 +294,11 @@ To ensure zero-impact synchronization between the VM and the Host Debug Overlay,
|
||||
3. **Single Source of Truth:** This model is the exclusive source of truth for both real-time inspection and frame-end certification, replacing legacy per-frame buffered fields.
|
||||
4. **Frame-Closed Log Metric:** `logs_count` in the snapshot represents the number of logs emitted in the last completed logical frame, not a transient in-flight counter.
|
||||
|
||||
## 11 Integration with CAP and Certification
|
||||
## 12 Integration with CAP and Certification
|
||||
|
||||
All debug and profiling data:
|
||||
All machine diagnostics and profiling data:
|
||||
|
||||
- feed the certification report
|
||||
- are collected deterministically
|
||||
- do not depend on external tools
|
||||
- feed the host-owned certification report;
|
||||
- are collected deterministically;
|
||||
- do not require a guest-visible debug ABI;
|
||||
- are consistent regardless of whether the Host HUD is active or not.
|
||||
|
||||
@@ -162,7 +162,7 @@ Without changing semantics.
|
||||
|
||||
## 11 Certification and Portability
|
||||
|
||||
The **PROMETEU Certification** is valid for all platforms.
|
||||
The host-owned **PROMETEU Certification** is valid for all platforms.
|
||||
|
||||
If a cartridge:
|
||||
|
||||
|
||||
@@ -110,44 +110,44 @@ This table describes content identity and storage layout, not live residency.
|
||||
|
||||
### 4.1 `TILES` asset contract in v1
|
||||
|
||||
Para `BankType::TILES`, o contrato v1 voltado para o runtime é:
|
||||
For `BankType::TILES`, the v1 runtime-facing contract is:
|
||||
|
||||
- `codec = NONE`
|
||||
- pixels serializados usam índices de paleta `u4` empacotados
|
||||
- paletas serializadas usam `RGB565` (`u16`, little-endian)
|
||||
- serialized pixels use packed `u4` palette indices
|
||||
- serialized palettes use `RGB565` (`u16`, little-endian)
|
||||
- `palette_count = 64`
|
||||
- a materialização em runtime pode expandir índices de pixel para um `u8` por pixel
|
||||
- runtime materialization may expand pixel indices to one `u8` per pixel
|
||||
|
||||
`NONE` para `TILES` significa que não há camada de codec genérica adicional além do próprio contrato do banco.
|
||||
For `TILES`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
||||
|
||||
Para a janela de transição atual:
|
||||
For the current transition window:
|
||||
|
||||
- `RAW` é um alias legado e depreciado de `NONE`
|
||||
- novos materiais publicados devem usar `NONE` como valor canônico
|
||||
- `RAW` is a legacy deprecated alias of `NONE`
|
||||
- newly published material must use `NONE` as the canonical value
|
||||
|
||||
Mesmo com `codec = NONE`, `TILES` ainda requer decode específico de banco a partir de seu payload serializado. O layout de bytes serializados não precisa, portanto, ser idêntico ao layout em memória.
|
||||
Even with `codec = NONE`, `TILES` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout.
|
||||
|
||||
#### 4.1.1 Metadata Normalization
|
||||
|
||||
Seguindo a `DEC-0004`, o campo `AssetEntry.metadata` deve ser estruturado de forma segmentada para evitar ambiguidades.
|
||||
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
|
||||
|
||||
Campos de metadados obrigatórios (efetivos) para `TILES` no nível raiz:
|
||||
Required effective metadata fields for `TILES` at the root level:
|
||||
|
||||
- `tile_size`: aresta do tile em pixels; valores válidos são `8`, `16`, ou `32`
|
||||
- `width`: largura total da folha do banco em pixels
|
||||
- `height`: altura total da folha do banco em pixels
|
||||
- `palette_count`: número de paletas serializadas para o banco
|
||||
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
||||
- `width`: total sheet width in pixels
|
||||
- `height`: total sheet height in pixels
|
||||
- `palette_count`: number of serialized palettes for the bank
|
||||
|
||||
Subárvores opcionais e informativas:
|
||||
Optional informative subtrees:
|
||||
|
||||
- `metadata.codec`: Configuração específica do codec/compressor (ex: dicionários, flags de compressão).
|
||||
- `metadata.pipeline`: Metadados informativos do processo de build do Studio (ex: source hashes, timestamps, tool versions).
|
||||
- `metadata.codec`: codec/compressor-specific configuration (for example dictionaries or compression flags).
|
||||
- `metadata.pipeline`: informative metadata from the Studio build process (for example source hashes, timestamps, or tool versions).
|
||||
|
||||
Regras de validação para `TILES` v1:
|
||||
Validation rules for `TILES` v1:
|
||||
|
||||
- `palette_count` deve ser `64`
|
||||
- `width * height` define o número de pixels indexados lógicos na folha decodificada
|
||||
- metadados adicionais podem existir, mas o contrato do runtime não deve depender deles para reconstruir o banco em memória (exceto se definidos na raiz como campos efetivos).
|
||||
- `palette_count` must be `64`
|
||||
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
||||
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
|
||||
|
||||
#### 4.1.2 Payload Layout
|
||||
|
||||
@@ -202,7 +202,8 @@ Rules:
|
||||
|
||||
- the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary;
|
||||
- canonical bank names are `GLYPH` and `SOUNDS`;
|
||||
- detailed occupancy inspection remains slot-based through slot references, not bank byte totals;
|
||||
- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals;
|
||||
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`;
|
||||
- any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract.
|
||||
|
||||
## 6 Load Lifecycle
|
||||
@@ -255,9 +256,9 @@ Therefore:
|
||||
- shutting down a cartridge can release bank residency independently of VM heap behavior.
|
||||
- the runtime must not keep the full `assets.pa` payload resident in RAM as a baseline requirement.
|
||||
|
||||
## 8 Bank Telemetry
|
||||
## 8 Bank Telemetry and Inspection Boundary
|
||||
|
||||
The runtime surfaces bank and slot statistics such as:
|
||||
The runtime may maintain bank and slot statistics such as:
|
||||
|
||||
- total bytes;
|
||||
- used bytes;
|
||||
@@ -266,7 +267,11 @@ The runtime surfaces bank and slot statistics such as:
|
||||
- slot occupancy;
|
||||
- resident asset identity per slot.
|
||||
|
||||
These metrics support debugging, telemetry, and certification-oriented inspection.
|
||||
These metrics support host-owned debugging, telemetry, and certification-oriented inspection.
|
||||
|
||||
Only bounded operational summaries belong to the public runtime contract.
|
||||
|
||||
Detailed per-slot inspection is valid for host tooling and runtime internals, but it must not be treated as a general guest-visible debug convenience API.
|
||||
|
||||
## 9 Preload
|
||||
|
||||
|
||||
@@ -15,6 +15,8 @@ It focuses on:
|
||||
|
||||
Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter.
|
||||
|
||||
Per `DEC-0009`, debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI.
|
||||
|
||||
## 1 Design Principles
|
||||
|
||||
The syscall ABI follows these rules:
|
||||
@@ -199,6 +201,15 @@ For `asset.load`:
|
||||
- `slot` is the target slot index;
|
||||
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
|
||||
|
||||
### Bank diagnostics surface (`bank`, v1)
|
||||
|
||||
`DEC-0009` narrows the public bank contract:
|
||||
|
||||
- `bank.slot_info` is host/debug tooling surface and is not part of the canonical long-term guest ABI;
|
||||
- JSON-on-the-wire bank inspection payloads are not valid public ABI;
|
||||
- if a public `bank.info` surface survives implementation cleanup, it must be reduced to a cheap deterministic operational summary aligned with the slot-first bank telemetry contract from [`15-asset-management.md`](15-asset-management.md);
|
||||
- if no machine-facing operational need remains, `bank.info` should also be removed from the public guest ABI.
|
||||
|
||||
### Composition surface (`composer`, v1)
|
||||
|
||||
The canonical frame-orchestration public ABI uses module `composer`.
|
||||
|
||||
@@ -9,6 +9,8 @@ It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), whi
|
||||
|
||||
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
|
||||
|
||||
Per `DEC-0009`, guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling.
|
||||
|
||||
## 1 Error Model: Faults vs Status Returns
|
||||
|
||||
Syscalls use a status-first hybrid model.
|
||||
@@ -61,6 +63,7 @@ Practical rule:
|
||||
|
||||
- `void` is allowed only for operations whose non-fault path is effectively unconditional success;
|
||||
- any operation with a meaningful operational non-success outcome must surface that outcome through `status`, not through absence of return values.
|
||||
- debug-only or certification-only convenience calls are not justified public ABI even if they could be given a valid return shape.
|
||||
|
||||
### No-op policy
|
||||
|
||||
@@ -77,6 +80,14 @@ This means operational problems must not be reclassified as:
|
||||
- `Trap`, when the failure is not structural;
|
||||
- `Panic`, when the failure is not an internal invariant break.
|
||||
|
||||
### Diagnostics boundary
|
||||
|
||||
These policy constraints also apply to observability surfaces:
|
||||
|
||||
- host-owned inspection and certification consumers may use runtime telemetry and internal host/runtime integration paths;
|
||||
- guest-visible syscalls must be justified by machine-facing operational needs, not by tooling convenience;
|
||||
- textual JSON diagnostics are not valid long-term public syscall ABI.
|
||||
|
||||
## 2 Capability System
|
||||
|
||||
Each syscall requires a declared capability.
|
||||
@@ -141,7 +152,7 @@ The system may account for:
|
||||
- cycles spent in syscalls;
|
||||
- allocations triggered by syscalls.
|
||||
|
||||
This keeps host interaction visible in certification, telemetry, and profiling.
|
||||
This keeps host interaction visible in host-owned certification, telemetry, and profiling.
|
||||
|
||||
## 6 Blocking and Long Operations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user