implements memcard
This commit is contained in:
@@ -116,7 +116,7 @@ No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- slots de memcard para `game` (fechado na decisao `011`);
|
||||
- slots de memcard para `game` (fechado na `spec 08`);
|
||||
- acesso cross-app;
|
||||
- sync remoto/cloud;
|
||||
- DB embutido como contrato de plataforma.
|
||||
|
||||
@@ -32,9 +32,9 @@ Justificativa curta:
|
||||
|
||||
- `011` foi fechada pela decisao `006`.
|
||||
- `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
|
||||
- `013` foi fechada pela decisao `011` (memcard `32 x 32KB`, ownership, identidade e copia fora do jogo).
|
||||
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/011`).
|
||||
- `014` fecha o contrato de `home` para apps sem abrir FS global.
|
||||
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre decisao `011` (`game`) e agenda `014` (`app`).
|
||||
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`).
|
||||
- a decisao `008` fixa o contrato status-first de `gfx`.
|
||||
- a decisao `009` fixa o contrato status-first de `audio`.
|
||||
- a decisao `010` fixa o contrato status-first de `asset`.
|
||||
@@ -48,7 +48,7 @@ Dependências principais:
|
||||
- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
|
||||
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
|
||||
- `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio
|
||||
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com decisao `011`/agenda `014` quando usar `fs`
|
||||
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs`
|
||||
- `010` depende de `16a` e da `009`
|
||||
|
||||
Regra de uso:
|
||||
|
||||
@@ -142,7 +142,7 @@ Para suportar este protocolo, a VM precisa expor API canonica para:
|
||||
|
||||
As seguintes agendas devem consumir esta decisao:
|
||||
|
||||
- `011-game-memcard-slots-surface-and-semantics.md` (decisao que absorveu a agenda `013`)
|
||||
- `spec 08-save-memory-and-memcard.md` (historico arquitetural em `learn/011`)
|
||||
- `014-app-home-filesystem-surface-and-semantics.md`
|
||||
- discussoes futuras de data bank
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ A agenda `003-filesystem-fault-semantics.md` existia para fechar fault semantics
|
||||
|
||||
Com o split de `fs` em:
|
||||
|
||||
- decisao `011` (`game` memcard slots);
|
||||
- `spec 08` (`game` memcard slots);
|
||||
- agenda `014` (`app` home sandbox);
|
||||
|
||||
ficou claro que:
|
||||
@@ -66,7 +66,7 @@ Se o dominio nao conseguir concluir a escrita segundo seu contrato de atomicidad
|
||||
- retorna `status` de falha;
|
||||
- nao mascara o resultado como sucesso.
|
||||
|
||||
### 6. Responsabilidade por perfil (movida para decisao `011` e agenda `014`)
|
||||
### 6. Responsabilidade por perfil (movida para `spec 08` e agenda `014`)
|
||||
|
||||
Fica sob responsabilidade das agendas de superficie:
|
||||
|
||||
@@ -89,10 +89,10 @@ A agenda `003-filesystem-fault-semantics.md` e considerada absorvida e removida.
|
||||
### Custos
|
||||
|
||||
- exige disciplina para manter a matriz de faults distribuida em duas agendas;
|
||||
- exige revisao de consistencia entre decisao `011` e agenda `014` antes de PR final de implementacao.
|
||||
- exige revisao de consistencia entre `spec 08` e agenda `014` antes de PR final de implementacao.
|
||||
|
||||
## Follow-up Obrigatorio
|
||||
|
||||
- `011-game-memcard-slots-surface-and-semantics.md` fecha a matriz de fault/status do perfil `game`;
|
||||
- `spec 08-save-memory-and-memcard.md` fecha a matriz de fault/status do perfil `game`;
|
||||
- `014-app-home-filesystem-surface-and-semantics.md` deve incluir a matriz de fault/status do perfil `app`;
|
||||
- specs `16`/`16a` devem absorver esta decisao quando o contrato estiver implementado e estavel.
|
||||
|
||||
@@ -19,7 +19,6 @@ Decisoes ativas:
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `006-vm-owned-stateful-core-contract.md`
|
||||
- `007-filesystem-fault-core-policy.md`
|
||||
- `011-game-memcard-slots-surface-and-semantics.md`
|
||||
|
||||
Decisoes implementadas e aposentadas (migradas para `learn/`):
|
||||
|
||||
@@ -32,6 +31,9 @@ Decisoes implementadas e aposentadas (migradas para `learn/`):
|
||||
- `010-asset-status-first-fault-and-return-contract.md`
|
||||
- spec: `../specs/15-asset-management.md`
|
||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`, `crates/console/prometeu-hal/src/asset_bridge.rs`, `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- `011-game-memcard-slots-surface-and-semantics.md`
|
||||
- spec: `../specs/08-save-memory-and-memcard.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
|
||||
- impl: `crates/console/prometeu-system/src/services/memcard.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/fs.rs`
|
||||
|
||||
Decisoes aposentadas que ja viraram spec:
|
||||
|
||||
|
||||
@@ -24,6 +24,7 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
|
||||
- [`008-gfx-status-first-fault-and-return-contract.md`](008-gfx-status-first-fault-and-return-contract.md)
|
||||
- [`009-audio-status-first-fault-and-return-contract.md`](009-audio-status-first-fault-and-return-contract.md)
|
||||
- [`010-asset-status-first-fault-and-return-contract.md`](010-asset-status-first-fault-and-return-contract.md)
|
||||
- [`011-game-memcard-slots-surface-and-semantics.md`](011-game-memcard-slots-surface-and-semantics.md)
|
||||
|
||||
## Rules
|
||||
|
||||
|
||||
@@ -1,149 +1,140 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Domain: virtual hardware: save memory
|
||||
Domain: virtual hardware: save memory
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/save-memory-and-memcard.md`](../learn/save-memory-and-memcard.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the runtime-facing persistent save surface of PROMETEU.
|
||||
This chapter defines the `game` persistence surface in PROMETEU.
|
||||
|
||||
The MEMCARD contract is:
|
||||
MEMCARD is a runtime-owned service layered on top of the runtime filesystem.
|
||||
|
||||
- explicit persistence controlled by the game;
|
||||
- fixed capacity determined by profile;
|
||||
- host-backed slot storage;
|
||||
- mandatory `commit()` to persist writes;
|
||||
- explicit cost and integrity metadata.
|
||||
Games do not get broad path-based filesystem access for saves. They use slot operations only.
|
||||
|
||||
Current model:
|
||||
## 2 Profile Contract (`game`)
|
||||
|
||||
- Slot A is the required primary save device;
|
||||
- additional slots remain future-facing surface.
|
||||
The v1 contract is fixed:
|
||||
|
||||
Each slot corresponds to a host file such as:
|
||||
- `32` slots per game (`slot_index: 0..31`);
|
||||
- each slot has up to `32KB` payload;
|
||||
- ownership is isolated by `app_id`;
|
||||
- persistence is explicit through `slot_commit`;
|
||||
- copy/export/import is a Hub/OS responsibility (outside game userland).
|
||||
|
||||
```
|
||||
MyGame_A.mem
|
||||
MyGame_B.mem
|
||||
```
|
||||
## 3 Slot Identity and Metadata
|
||||
|
||||
The runtime mounts this file as a **persistent storage device**.
|
||||
Each slot has runtime-owned metadata:
|
||||
|
||||
## 2 Capacity and CAP
|
||||
- `app_id` owner;
|
||||
- `slot_index`;
|
||||
- `save_uuid`;
|
||||
- `generation`;
|
||||
- `checksum`;
|
||||
- `payload_size`;
|
||||
- `state`.
|
||||
|
||||
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
|
||||
State values:
|
||||
|
||||
### 2.1 Suggested sizes
|
||||
- `0 = EMPTY`
|
||||
- `1 = STAGED`
|
||||
- `2 = COMMITTED`
|
||||
- `3 = CORRUPT`
|
||||
|
||||
| Profile | Size |
|
||||
`generation` and `checksum` are not manually controlled by game code:
|
||||
|
||||
- `generation` increments on successful `slot_commit`;
|
||||
- `checksum` is recalculated by runtime for committed payload integrity.
|
||||
|
||||
## 4 Host ABI Surface (v1)
|
||||
|
||||
Canonical module: `mem` (version `1`).
|
||||
|
||||
| Operation | Signature |
|
||||
| --- | --- |
|
||||
| JAM | 8 KB |
|
||||
| STANDARD | 32 KB |
|
||||
| ADVANCED | 128 KB |
|
||||
| `slot_count` | `mem.slot_count() -> (status:int, count:int)` |
|
||||
| `slot_stat` | `mem.slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)` |
|
||||
| `slot_read` | `mem.slot_read(slot:int, offset:int, max_bytes:int) -> (status:int, payload_hex:string, bytes_read:int)` |
|
||||
| `slot_write` | `mem.slot_write(slot:int, offset:int, payload_hex:string) -> (status:int, bytes_written:int)` |
|
||||
| `slot_commit` | `mem.slot_commit(slot:int) -> status:int` |
|
||||
| `slot_clear` | `mem.slot_clear(slot:int) -> status:int` |
|
||||
|
||||
The game **cannot exceed** this size.
|
||||
`status` is always the first return slot.
|
||||
|
||||
Attempts to write above the limit result in an error.
|
||||
### 4.1 Byte transport note (v1)
|
||||
|
||||
## 3 Peripheral API (v0.1)
|
||||
Current ABI transport for memcard payload is `payload_hex:string`.
|
||||
|
||||
### 3.1 Logical Interface
|
||||
This is a temporary transport form until VM-owned bytes (`HeapRef<Bytes>`) is exposed in the host ABI path.
|
||||
|
||||
The MEMCARD exposes a **simple single-blob API**:
|
||||
## 5 Operation Semantics
|
||||
|
||||
```
|
||||
mem.read_all() -> byte[]
|
||||
mem.write_all(byte[])
|
||||
mem.commit()
|
||||
mem.clear()
|
||||
mem.size() -> int
|
||||
```
|
||||
### `slot_count`
|
||||
|
||||
### 3.2 Operation Semantics
|
||||
- returns slot capacity visible to game profile (`32`);
|
||||
- does not depend on slot content.
|
||||
|
||||
#### `read_all()`
|
||||
### `slot_stat`
|
||||
|
||||
- Returns all persisted content
|
||||
- If the card is empty, returns a zeroed buffer
|
||||
- Cycle cost proportional to size
|
||||
- returns current state and integrity/version metadata for one slot.
|
||||
|
||||
#### `write_all(bytes)`
|
||||
### `slot_read`
|
||||
|
||||
- Writes the buffer **to temporary memory**
|
||||
- Does not persist immediately
|
||||
- Fails if `bytes.length > mem.size()`
|
||||
- reads from staged content when present, otherwise committed content;
|
||||
- returns empty payload with success when offset is beyond current payload end.
|
||||
|
||||
#### `commit()`
|
||||
### `slot_write`
|
||||
|
||||
- Persists data to the device
|
||||
- **Mandatory** operation
|
||||
- Simulates hardware flush
|
||||
- May fail (e.g., I/O, simulated corruption)
|
||||
- writes into slot staging buffer (does not persist directly);
|
||||
- supports offset writes;
|
||||
- does not allow resulting payload above `32KB`.
|
||||
|
||||
#### `clear()`
|
||||
### `slot_commit`
|
||||
|
||||
- Zeroes the card content
|
||||
- Requires `commit()` to persist
|
||||
- persists staged payload for one slot;
|
||||
- commit is atomic at slot operation level (all-or-error, no silent partial success).
|
||||
|
||||
#### `size()`
|
||||
### `slot_clear`
|
||||
|
||||
- Returns total card capacity in bytes
|
||||
- clears staged content and removes committed slot payload.
|
||||
|
||||
## 4 Explicit Commit Rule
|
||||
## 6 Status Codes (Domain-Owned)
|
||||
|
||||
PROMETEU **does not save automatically**.
|
||||
Minimum status catalog:
|
||||
|
||||
Without `commit()`:
|
||||
- `0 = OK`
|
||||
- `1 = EMPTY`
|
||||
- `2 = NOT_FOUND`
|
||||
- `3 = NO_SPACE`
|
||||
- `4 = ACCESS_DENIED`
|
||||
- `5 = CORRUPT`
|
||||
- `6 = CONFLICT`
|
||||
- `7 = UNAVAILABLE`
|
||||
- `8 = INVALID_STATE`
|
||||
|
||||
- data remains volatile
|
||||
- can be lost upon exiting the game
|
||||
- simulates abrupt hardware shutdown
|
||||
## 7 Fault Classification
|
||||
|
||||
## 5 Execution Cost (Cycles)
|
||||
MEMCARD follows `16a`:
|
||||
|
||||
All MEMCARD operations have an explicit cost.
|
||||
- `Trap`: structural violations (invalid slot index, invalid call shape, invalid window value type/range);
|
||||
- `status`: operational domain conditions;
|
||||
- `Panic`: runtime invariant break only.
|
||||
|
||||
### 5.1 Example (illustrative values)
|
||||
Silent no-op is forbidden for operations with operational failure paths.
|
||||
|
||||
| Operation | Cost |
|
||||
| --- | --- |
|
||||
| read_all | 1 cycle / 256 bytes |
|
||||
| write_all | 1 cycle / 256 bytes |
|
||||
| commit | fixed + proportional cost |
|
||||
## 8 Runtime Layering and Storage Mapping
|
||||
|
||||
These costs appear:
|
||||
MEMCARD is a domain layer over runtime FS.
|
||||
|
||||
- in the profiler
|
||||
- in the frame timeline
|
||||
- in the CAP report
|
||||
Runtime host mapping for v1 is namespace-isolated by `app_id`, for example:
|
||||
|
||||
## 6 `.mem` File Format
|
||||
`/user/games/<app_id>/memcard/slot_<NN>.pmem`
|
||||
|
||||
The MEMCARD file has a simple and robust format.
|
||||
The exact host-side file naming is internal to runtime/host as long as ownership and isolation guarantees are preserved.
|
||||
|
||||
### 6.1 Header
|
||||
## 9 Explicit Persistence Rule
|
||||
|
||||
| Field | Size |
|
||||
| --- | --- |
|
||||
| Magic (`PMEM`) | 4 bytes |
|
||||
| Version | 1 byte |
|
||||
| Cart ID | 8 bytes |
|
||||
| Payload Size | 4 bytes |
|
||||
| CRC32 | 4 bytes |
|
||||
PROMETEU does not auto-save slot staging data.
|
||||
|
||||
### 6.2 Payload
|
||||
|
||||
- Binary buffer defined by the game
|
||||
- Fixed size
|
||||
- Content interpreted only by the game
|
||||
|
||||
## 7 Integrity and Security
|
||||
|
||||
- CRC validates corruption
|
||||
- Cart ID prevents using wrong save
|
||||
- Version allows future format evolution
|
||||
- Runtime can:
|
||||
- warn of corruption
|
||||
- allow card reset
|
||||
Without `slot_commit`, writes remain staged and are not guaranteed as persisted committed state.]
|
||||
@@ -156,6 +156,22 @@ Return shape must also follow the operational policy in [`16a-syscall-policies.m
|
||||
- operations with no real operational error path may remain `void` (`ret_slots = 0`);
|
||||
- stack shape remains strict in both cases and must match syscall metadata exactly.
|
||||
|
||||
### MEMCARD game surface (`mem`, v1)
|
||||
|
||||
The game memcard profile uses module `mem` with status-first return shapes.
|
||||
`mem` is a domain layer backed by runtime `fs` (it is not a separate storage backend).
|
||||
|
||||
Canonical operations in v1 are:
|
||||
|
||||
- `mem.slot_count() -> (status, count)`
|
||||
- `mem.slot_stat(slot) -> (status, state, used_bytes, generation, checksum)`
|
||||
- `mem.slot_read(slot, offset, max_bytes) -> (status, payload_hex, bytes_read)`
|
||||
- `mem.slot_write(slot, offset, payload_hex) -> (status, bytes_written)`
|
||||
- `mem.slot_commit(slot) -> status`
|
||||
- `mem.slot_clear(slot) -> status`
|
||||
|
||||
Semantics and domain status catalog are defined by [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
## 7 Syscalls as Callable Entities (Not First-Class)
|
||||
|
||||
Syscalls behave like call sites, not like first-class guest values.
|
||||
|
||||
@@ -66,12 +66,16 @@ Example groups:
|
||||
- `gfx`
|
||||
- `audio`
|
||||
- `asset`
|
||||
- `memcard`
|
||||
- `fs` (includes game memcard module `mem` in v1)
|
||||
|
||||
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
||||
|
||||
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
|
||||
|
||||
Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1.
|
||||
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
|
||||
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
Reference in New Issue
Block a user