[PERF] Runtime Introspection Syscalls
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user