150 lines
2.9 KiB
Markdown
150 lines
2.9 KiB
Markdown
# Save Memory and MEMCARD
|
|
|
|
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.
|
|
|
|
The MEMCARD contract is:
|
|
|
|
- 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.
|
|
|
|
Current model:
|
|
|
|
- Slot A is the required primary save device;
|
|
- additional slots remain future-facing surface.
|
|
|
|
Each slot corresponds to a host file such as:
|
|
|
|
```
|
|
MyGame_A.mem
|
|
MyGame_B.mem
|
|
```
|
|
|
|
The runtime mounts this file as a **persistent storage device**.
|
|
|
|
## 2 Capacity and CAP
|
|
|
|
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
|
|
|
|
### 2.1 Suggested sizes
|
|
|
|
| Profile | Size |
|
|
| --- | --- |
|
|
| JAM | 8 KB |
|
|
| STANDARD | 32 KB |
|
|
| ADVANCED | 128 KB |
|
|
|
|
The game **cannot exceed** this size.
|
|
|
|
Attempts to write above the limit result in an error.
|
|
|
|
## 3 Peripheral API (v0.1)
|
|
|
|
### 3.1 Logical Interface
|
|
|
|
The MEMCARD exposes a **simple single-blob API**:
|
|
|
|
```
|
|
mem.read_all() -> byte[]
|
|
mem.write_all(byte[])
|
|
mem.commit()
|
|
mem.clear()
|
|
mem.size() -> int
|
|
```
|
|
|
|
### 3.2 Operation Semantics
|
|
|
|
#### `read_all()`
|
|
|
|
- Returns all persisted content
|
|
- If the card is empty, returns a zeroed buffer
|
|
- Cycle cost proportional to size
|
|
|
|
#### `write_all(bytes)`
|
|
|
|
- Writes the buffer **to temporary memory**
|
|
- Does not persist immediately
|
|
- Fails if `bytes.length > mem.size()`
|
|
|
|
#### `commit()`
|
|
|
|
- Persists data to the device
|
|
- **Mandatory** operation
|
|
- Simulates hardware flush
|
|
- May fail (e.g., I/O, simulated corruption)
|
|
|
|
#### `clear()`
|
|
|
|
- Zeroes the card content
|
|
- Requires `commit()` to persist
|
|
|
|
#### `size()`
|
|
|
|
- Returns total card capacity in bytes
|
|
|
|
## 4 Explicit Commit Rule
|
|
|
|
PROMETEU **does not save automatically**.
|
|
|
|
Without `commit()`:
|
|
|
|
- data remains volatile
|
|
- can be lost upon exiting the game
|
|
- simulates abrupt hardware shutdown
|
|
|
|
## 5 Execution Cost (Cycles)
|
|
|
|
All MEMCARD operations have an explicit cost.
|
|
|
|
### 5.1 Example (illustrative values)
|
|
|
|
| Operation | Cost |
|
|
| --- | --- |
|
|
| read_all | 1 cycle / 256 bytes |
|
|
| write_all | 1 cycle / 256 bytes |
|
|
| commit | fixed + proportional cost |
|
|
|
|
These costs appear:
|
|
|
|
- in the profiler
|
|
- in the frame timeline
|
|
- in the CAP report
|
|
|
|
## 6 `.mem` File Format
|
|
|
|
The MEMCARD file has a simple and robust format.
|
|
|
|
### 6.1 Header
|
|
|
|
| Field | Size |
|
|
| --- | --- |
|
|
| Magic (`PMEM`) | 4 bytes |
|
|
| Version | 1 byte |
|
|
| Cart ID | 8 bytes |
|
|
| Payload Size | 4 bytes |
|
|
| CRC32 | 4 bytes |
|
|
|
|
### 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
|