Sprinter-SDCC/docs/memory-management.md

# Управление памятью в sprinter-cc

Документ описывает модель памяти Sprinter (Sp2000), режимы памяти обёртки
`sprinter-cc` и способы размещения кода/данных: single-page, split, банки
(трамплины) и резидентный код окна W3 (`--w3`).

Всё в этом документе подтверждено сборкой и прогоном в MAME v3.06 / DSS 1.71.57
(см. `tests/w3probe`, `tests/banktest`, `tests/banklocl`).

---

## 1. Аппаратная модель памяти

Z80 видит 64 КБ, разбитые на **четыре окна по 16 КБ**. Каждое окно независимо
маппится на физическую страницу через порт-регистр страницы:

| Окно | Адреса        | Порт страницы | Назначение по умолчанию |
|------|---------------|---------------|--------------------------|
| W0   | `0x0000-0x3FFF` | `0x82`      | **DSS / BIOS** (RST-ы, системные вызовы) |
| W1   | `0x4000-0x7FFF` | `0xA2`      | приложение |
| W2   | `0x8000-0xBFFF` | `0xC2`      | приложение |
| W3   | `0xC000-0xFFFF` | `0xE2`      | приложение / графика / банки |

- Запись в порт `0x{8/A/C/E}2` меняет физ-страницу окна; чтение возвращает
  текущую страницу.
- **W0 занят DSS/BIOS** — там живут RST-обработчики (`RST #08` BIOS, `RST #10`
  ESTEX). Пока в W0 стоит системная страница, вызовы доступны; подменять W0
  нельзя без потери RST-ов.
- «Неиспользуемое» окно маппится на **специальную страницу `#FF`**: чтение даёт
  `0xFF`, запись игнорируется. Это ключевая причина «молчаливой» порчи данных —
  см. §7.

### Порты в C

`<sprinter.h>` даёт SFR-обёртки: `_io_page_w0..w3` (чтение/запись порта),
`sprinter_page_w0..w3(page)`.

---

## 2. Как DSS загружает EXE

Из документации DSS, последовательность `EXEC`:

1. Открыть exe-файл на чтение.
2. Считать префикс exe в рабочую область.
3. **Выделить блок памяти** размером под весь файл (если `loader==0`) или под
   первичный загрузчик (`loader>0`).
4. Сохранить стек.
5. **Подключить страницы** выделенного блока в окна (последовательно от окна
   адреса загрузки: W1→W2→W3…).
6. Построить префикс запуска → регистр `IX`.
7. Считать файл по адресу загрузки (смещение 16 в заголовке).
8. Закрыть exe, **если это не первичный загрузчик** (`loader==0`).
9. Установить `SP` = значение из смещения 20 (адрес стека).
10. Передать управление по адресу из смещения 18 (entry).

**Следствия, на которых стоит вся схема памяти:**

- DSS выделяет **число страниц по размеру образа**: `<16 КБ` → 1 страница,
  `16..32 КБ` → 2, `32..48 КБ` → 3. Лишние окна = страница `#FF`.
- Страницы маппятся **подряд** начиная с окна адреса загрузки. Образ, тянущийся
  `0x4100..0xFFFF` (3 страницы), даёт W1+W2+W3 замапленными автоматически —
  **это и есть база для резидентного кода W3** (§6, подход A).
- `loader>0` (multi-bank .exe) → DSS грузит только HOME-часть и **оставляет
  файл открытым** (handle в `IX-3`), а crt0 дочитывает банки сам (§5).

Упаковкой в этот формат занимается `toolchain/mkexe`.

---

## 3. Правила стека (критично)

- **`SP ≤ 0xBFFF`** при вызовах DSS (ESTEX, `RST #10`).
- **`SP ≥ 0x8000`** при вызовах некоторых функций BIOS (`RST #08`).
- Пересечение этих требований → **стек обязан жить в W2** (`0x8000-0xBFFF`).
  По умолчанию `SP` инициализируется в `0xBFFE`.

Проверено (`tests/w3probe`): во всех режимах на входе `main` `SP ≈ 0xBFFC`, т.е.
в W2.

**Chicken-and-egg для split-режимов** (small/huge): DSS ставит `SP=0xBFFE` из
заголовка, но для программ `<16 КБ` окно W2 ещё не выделено (там `#FF`). Пуши
туда теряются, первый `call` возвращается в мусор. Поэтому `crt0_small`/
`crt0_banked` сначала работают на **загрузочном стеке в W1** (реальное ОЗУ),
маппят W2 и только потом переставляют `SP=0xBFFE`. Маппинг W2 делается через
**ESTEX `$3A SETWIN2`** (не BIOS `$C4`+OUT — тому нужен стек уже в W2).

---

## 4. Режимы памяти

Выбираются флагом `sprinter-cc --memory MODE` (по умолчанию `tiny`). Режим задаёт
адрес кода, размещение данных, crt0 и наличие банков.

| Режим  | CODE | DATA/BSS | Стек | Банки | crt0 | Первичный загрузчик |
|--------|------|----------|------|-------|------|----------------------|
| `tiny`   | W2 `0x8100` | за кодом (W2) | W2 | — | `crt0.s` | нет (1 страница) |
| `small`  | W1 `0x4100` | за кодом (W1→W2) | W2 | — | `crt0_small.s` | да (сам маппит W2) |
| `big`    | W2 `0x8100` | за кодом (W2) | W2 | W1 (трамплины) | `crt0_banked.s` (BANK_W1) | да |
| `huge`   | W1 `0x4100` | за кодом (W1→W2) | W2 | W3 (трамплины) | `crt0_banked.s` | да |
| `manual` | явно | явно | W2 | — | `crt0.s` | зависит |

Во всех режимах **DATA цепляется линкером сразу за кодом** (`--data-loc 0`), а не
кладётся по фиксированному адресу. Раньше `huge` использовал фиксированный
`DATA=0x8000`, что ломалось при коде `>16 КБ` (код перетекал в W2 и накрывал
DATA); сейчас DATA динамически идёт за концом кода.

### 4.1 `tiny` — всё в одной странице

```
0x8000..0x80FF  зарезервировано (startup-prefix)
0x8100          _start / _CODE … _DATA … _BSS … _HEAP
0xBB00          heap top (по умолчанию)
0xBFFE          стек ↓
```

- Один блок 16 КБ, DSS маппит его в W2. W1 и W3 = `#FF`.
- Ничего выделять/маппить не надо; `crt0.s` предполагает, что W2 уже дан DSS.
- Практический потолок кода+данных+кучи+стека ≈ 14 КБ.
- `--code-loc 0x8100 --data-loc 0`; mkexe `-L 0x8100 -E 0x8100 -S 0xBFFE`.

### 4.2 `small` — CODE в W1, данные перетекают в W2

```
0x4100          _CODE …            (W1)
  … за кодом →  _DATA _BSS _HEAP   (W1, перетекает в W2)
0xBB00          heap top
0xBFFE          стек ↓             (W2)
```

- Покрывает ~0..30 КБ (код+данные вместе).
- `crt0_small.s` авто-определяет W2: читает порт `0xC2`. Если `≠0xFF` — DSS уже
  дал W2 (образ `>16 КБ`), маппить не надо. Если `=0xFF` — сам выделяет страницу
  (`ESTEX $3D GETMEM`) и маппит (`ESTEX $3A SETWIN2`).
- `--code-loc 0x4100 --data-loc 0`.

### 4.3 `big` — tiny + банки в W1

- База как `tiny` (CODE+DATA+стек в W2, `0x8100`).
- **Свапаемые банки в W1** (`0x4000-0x7FFF`, порт `0xA2`), вызываются через
  трамплины (§5). `crt0_banked.s` собирается с `BANK_W1=1`.
- mkexe получает `-B 0x4000` (банки живут в W1). Виртуальный адрес банка N =
  `0x{N}4000`.
- W3 свободно — доступно под графику или резидентный код (`--w3`).

### 4.4 `huge` — small + банки в W3

- База как `small` (CODE `0x4100`, DATA за кодом, авто-детект W2).
- **Свапаемые банки в W3** (`0xC000-0xFFFF`, порт `0xE2`), через трамплины.
  Виртуальный адрес банка N = `0x{N}C000`.
- `crt0_banked.s` (без `BANK_W1`) грузит банки из .exe после старта.

### 4.5 `manual` — явное размещение

`--memory manual --memory-manual SPEC`, где SPEC = список `KEY=VAL`:
`CODE=W1|W2`, `DATA=W1|W2|SAME`, `BANKED=W1|W3`. Плюс прямые `--code-loc` /
`--data-loc` / `-L` / `-E` / `-S` перекрывают дефолты любого режима.

---

## 5. Банки и трамплины (`--bank`)

Для `big`/`huge`. Модуль-банк собирается в отдельную область и линкуется по
**виртуальному 24-битному адресу** (`bank_id` в старшем байте):

```
sprinter-cc --memory huge --bank 1=engine.c --bank 2=audio.c -o app.exe main.c
```

- Банк N компилируется `--codeseg/--constseg/--dataseg BANKN`, линкуется
  `-Wl-b_BANKN=0x{N}C000` (huge) или `0x{N}4000` (big).
- `main.c` обязан объявить `const uint8_t n_banks = N;` — `crt0_banked` читает
  это **до gsinit**, поэтому только `const` (инициализатор ещё не скопирован).
- Функции банка помечаются `__banked` — SDCC генерирует вызов через трамплин
  `___sdcc_bcall_ehl` (в `_CODE`/W1, всегда замаплен): он сохраняет текущую
  страницу окна, маппит нужный банк (`_bank_pages[id]`), `jp` в функцию, по
  возврату восстанавливает страницу.
- Загрузка: mkexe пакует `header + HOME + bank1(16К) + bank2(16К)…`,
  `loader=размер HOME`; `crt0_banked` выделяет страницы (`GETMEM`), маппит и
  дочитывает каждый банк `ESTEX READ` из открытого файла.
- Проверка размеров банков — `toolchain/check_banks.py` (часть отчёта
  раскладки, см. §10).

Writable bank-local данные возможны, но с оговорками — см.
`memory/bank_local_data_pattern`.

---

## 6. Резидентный код окна W3 (`--w3`)

**Альтернатива банкам без трамплинов.** Модуль размещается резидентно в W3
(`0xC000`) и вызывается **прямым `call`** — как обычная функция. Работает во
**всех режимах** (`tiny|small|big|huge`); по умолчанию подразумевает `small`.

```
sprinter-cc --w3 render.c -o app.exe main.c            # → small
sprinter-cc --memory huge --w3 render.c --bank 1=lvl.c -o app.exe main.c
```

**Как работает (подход A):** образ с областью `W3CODE`@`0xC000` тянется до `0xC0xx`
(≥3 страницы), и DSS сам маппит W3 при загрузке (§2) — **загрузчик в crt0 не
нужен** (кроме huge). Прямые вызовы резолвятся линкером в реальные `0xC0xx`.

**Механизм сборки:**
- W3-модуль компилируется `--codeseg W3CODE --constseg W3CODE` — код и rodata в
  W3. **`--dataseg` НЕ переопределяется**: писучие статики уходят в обычный
  `_DATA` (W2). Отсюда правило «в W3 только код + rodata».
- Линк `-Wl-b_W3CODE=0xC000`.

**Раскладка страниц по режимам (проверено MAME):**

| Режим | W1 | W2 | W3 |
|-------|----|----|----|
| tiny  | `#FF` (не исп.) | код+данные | **резидент** |
| small | код | данные | **резидент** |
| big   | банк (трамплин) | код+данные | **резидент** |
| huge  | код | данные | **резидент делит окно с трамплин-банками** |

**huge — особый случай (резидент + банки в одном окне W3):**
- `crt0_banked` под `.ifdef W3_RESIDENT` захватывает физ-страницу резидента
  (`in a,(0xE2)`) сразу после загрузки DSS и **возвращает её дефолтом** после
  цикла загрузки банков (иначе в W3 остался бы последний банк).
- Трамплин на каждый `__banked`-вызов сам сохраняет/восстанавливает страницу
  W3 — поэтому дефолтная страница обязана быть резидентной.
- mkexe получает флаг `-W` (разрешить HOME тянуться в W3 при наличии W3-банков —
  намеренное совмещение).

**Правила разработчика:**
- Код в W3 **не переключает** страницу W3.
- Код в W1/W2, свапающий W3 на другую страницу (скретч, графика), обязан
  **вернуть исходную** (`in a,(0xE2)` → работа → `out (0xE2),a`); оборачивать в
  `DI/EI`, если есть ISR, дёргающий W3.
- В W3 — **только код + rodata**, писучих переменных там быть не должно.
- Из `__banked`-контекста (пока в W3 замаплен банк) резидентный W3-код
  **недостижим** транзитивно. Обратное — резидент → `__banked` через трамплин
  W1 — **работает** (трамплин вернёт резидентную страницу перед `ret`).

Подробности и артефакты — `memory/w3_resident_code`, тест `tests/w3probe`.

---

## 7. Куча и стек

- **Стек**: init `SP=0xBFFE`, растёт вниз. Меняется через `-S 0xADDR`.
- **Куча**: от конца `_BSS` вверх до `___sdcc_heap_end` (по умолчанию `0xBB00` →
  ~1278 байт под стек). `malloc` берёт `&___sdcc_heap_end` как потолок.
- `runtime/heap.s` — динамическая куча (авто-размер = зазор BSS…heap_top), НЕ
  фиксированный `.ds`.
- `--stack-size N` регенерирует `heap_top` как `HEAP_TOP = 0xBFFF - N`, зажимая
  рост кучи ради стека.

---

## 8. Семейство crt0

Выбирается режимом; `--crt0=TYPE` перекрывает.

| crt0 | Файл | Для чего |
|------|------|----------|
| `default` | `runtime/crt0.s` | tiny/manual; парсит argv, argv[0] через APPINFO |
| `minimal` | `runtime/crt0_minimal.s` | tiny без argv (меньше размер) |
| `small`   | `runtime/crt0_small.s` | small; авто-детект/выделение W2 |
| `banked`  | `runtime/crt0_banked.s` | big/huge; авто-детект W2 + загрузка банков |

`crt0`/`bank.s` собираются **пер-сборка** внутри `sprinter-cc` (с префиксами
`BANK_W1` / `W3_RESIDENT` / `DEBUG_RT`), а не бандлятся в библиотеку.

---

## 9. Типовые грабли

- **`static`-переменные читаются как `0xFF` / не меняются** — DATA попала в
  невыделенное окно (`#FF`). Причина: код и данные в разных окнах при образе
  `<16 КБ`, где DSS дал только одну страницу. Лечится правильным режимом
  (`small`/`huge`) или единым окном (`tiny`). См.
  `memory/sprinter_memory_modes`.
- **Крэш после первого `call` в split-режиме** — стек ещё в невыделенном W2.
  Решает загрузочный стек в W1 (уже в crt0).
- **Банк «прыгает в мусор»** — таблица `_bank_pages[]` в `_DATA` занулилась
  gsinit’ом; она обязана жить в `_CODE`. Уже исправлено в `bank.s`.
- **`--w3`: резидент недоступен из банка** — ожидаемо (см. §6); держи вход в
  резидент только из W1/W2 или из самого W3-кода.

---

## 10. Отчёт по раскладке памяти (после линковки)

`sprinter-cc` печатает отчёт `toolchain/check_banks.py` для **любой** модели
памяти (по `.map`).  Показывает, где легли код/данные и **сколько свободно**
в каждом окне и банке:

```
memory: huge — CODE в W1 (0x4100), DATA→W2, банки в W3
  _CODE         @ 0x4100  size   3767  (W1)  → 0x4FB7
  данные        @ 0x4FB7  size    336  (W1)  → 0x5107   [_DATA/_BSS/_INITIALIZED/…]
  статика до 0x5107  —  куча 0x5107..0xBB00 (27129 Б), стек 0xBB00..0xBFFE (1279 Б)
  _W3CODE       @ 0xC000  size    249  (резидент W3)  → 0xC0F9, 16135 Б свободно до 0x10000  OK
  _BANK1        @ 0x0001C000  size    219 / 16384 ( 1.3%)  → 16165 Б свободно  OK
```

- `_CODE` / `данные` — окно (W1/W2), размер, конец; строка `статика … куча …
  стек …` = свободное место в W1/W2 (под кучу malloc до `___sdcc_heap_end` и
  под стек).
- `_W3CODE` — только при `--w3`: остаток окна W3.
- `_BANKn` — только при `--bank`: занятость/остаток каждого 16 КБ-банка.
- Ненулевой выход (проглатывается `|| true`), если банк > 16 КБ или статика
  заехала за `heap_top`/`0xC000`.
```