mdview2: статус-бар в отдельный модуль, упростить alloc_set_storage

- mdview2_status.c: вынести статус-бар/меню/спиннер из ядра
- mdview2.c: убрать retry-цикл в alloc_set_storage (fail-fast вместо
  ложной устойчивости — при нехватке EMM под индекс контент тоже не влезет)
- mdview2.h: дополнить экспортами статус-модуля
- mdview2_md.c / mdview2_raw.c: зачистка после расщепления
- mdview/mdview.c: переименовать scroll_* → md_scroll_* (симметрия)
- docs/fast_ram.md, docs/turboc.txt: добавить справочные доки
- examples/mdview2/README.MD, READMEBG.MD: обновить описание

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-06-26 23:19:00 +03:00
parent 05916a3cc6
commit 1b78dda125
12 changed files with 1802 additions and 443 deletions
+195
View File
@@ -0,0 +1,195 @@
# Fast RAM (Быстрое ОЗУ / «КЭШ-ОЗУ») на Sprinter
Сводка по результатам изучения документации платформы. Источники:
- `docs/converted/Architecture.txt` — официальное «Описание архитектуры» (раздел
«Распределение основной памяти»).
- `docs/converted/ARHITECT.txt` — ранняя редакция того же документа (про загрузку
конфигураций ППЛМ).
- `docs/converted/IvanMak.txt` / `docs/converted/Parinov.txt` / `docs/converted/Forum.txt`
и `docs/part2/forum.txt` — форумные ответы Дениса Паринова (Sprinter Team) и
руководство Ивана Мака (раздел «7 КЭШ-ОЗУ»).
- `docs/part2/accelerator_doc.txt` — ограничение акселератора.
- `docs/samples/sprinterIntLib.asm` — практический пример temporary-off / restore.
> **Терминология.** В документации одно и то же ОЗУ называется тремя именами:
> **Fast RAM**, **Быстрое ОЗУ** и **«КЭШ-ОЗУ»**. Это *не* кэш в формальном смысле
> (нет автоматического заполнения/вытеснения) — это отдельный массив статической
> памяти, в котором процессор работает на полной частоте **без тактов ожидания**.
> Имя «КЭШ» — историческое, по аналогии с кэшем на КР537РУ10 в Pentagon-128.
---
## 1. Что это и зачем
* **Объём:** 64 КБ статической памяти (SRAM), отдельной от основного DRAM-SIMM
(4 МБ) и от видео-ОЗУ (256 КБ).
* **Скорость:** процессор обращается к Fast RAM на полной тактовой частоте
(21 МГц) **без wait-state'ов**. Основное ОЗУ (DRAM) требует тактов ожидания,
поэтому код и данные в Fast RAM исполняются/читаются заметно быстрее.
* **Назначение:** разместить «горячий» код или данные (внутренние циклы,
таблицы, буферы), которые критичны по скорости.
* **Системная роль:** Fast RAM также используется механизмом
переконфигурирования ППЛМ — именно в неё BIOS грузит данные новой
конфигурации и флаг `ACEX_30K_LOADING` (старое имя `FLEX_10K_LOADING`) перед
программным сбросом. Поэтому к Fast RAM нельзя относиться как к «своей» памяти,
которая всегда сохраняется (см. §5).
---
## 2. Карта физических страниц
Память делится на 16 КБ-блоки с однобайтовым физическим номером:
| Тип памяти | Физические номера страниц |
|---------------|---------------------------|
| Основное ОЗУ | `#00..#4F`, видео-область `#50..#5F`, ... |
| ПЗУ (ROM) | `#E0..#EF` |
| **Fast RAM** | `#F0..#FF` |
> Хотя диапазон номеров Fast RAM — `#F0..#FF` (16 значений), **реально
> используются только биты 1 и 2** номера страницы. То есть адресуются 4
> страницы × 16 КБ = **64 КБ**: `#F0`, `#F2`, `#F4`, `#F6`.
---
## 3. Как включать Fast RAM
Есть **два способа** подключить Fast RAM в адресное пространство Z80.
### Способ A. Pentagon-style через порт `#FB` / `#7B` (в окно 0)
Включается «как кэш в Pentagon»: подключает 16 КБ Fast RAM в **окно 0**
(`#0000..#3FFF`) вместо ПЗУ. Переключение — *побочный эффект чтения порта*
(значение в `A` после `IN` — мусор, важен сам факт обращения):
```asm
DI
IN A,(#FB) ; включить Fast-RAM — 16 КБ в окно 0 (#0000..#3FFF)
; ... ваш код / работа с Fast RAM ...
IN A,(#7B) ; выключить Fast-RAM (вернуть ПЗУ в окно 0)
EI
```
* `IN A,(#FB)`**включить**.
* `IN A,(#7B)`**выключить**.
> **Конфликт портов.** Порт `#FB` (и `#4F`) — это также порт COVOX/Blaster-а.
> Вывод (`OUT`) в `#FB` управляет звуком, а *чтение* (`IN`) — переключает
> Fast RAM. Не путать направления обращения.
### Способ B. Как ПЗУ — через PAGE0 (`#82`) + порт `#1FFD`
Fast RAM-страница (`#F0..#FF`) выбирается в PAGE0 и подключается на место ПЗУ
в окно 0 через спец-порт `#1FFD`:
```asm
; выбрать физическую страницу Fast RAM в PAGE0
LD A, #F0 ; номер страницы Fast RAM
OUT (#82), A ; PAGE0 = страница в окно 0
LD A,1 ; 1 → ОЗУ (выбранная страница) в #0000..#3FFF
LD BC,#1FFD
OUT (C),A
; ...
LD A,0 ; 0 → вернуть ПЗУ в #0000..#3FFF
LD BC,#1FFD
OUT (C),A
```
* Порты PAGE: `PAGE0=#82`, `PAGE1=#A2`, `PAGE2=#C2`, `PAGE3=#E2`.
**Чтение** порта PAGE возвращает текущий номер страницы.
* Эти адреса портов формально могут отличаться в других конфигурациях ППЛМ —
правильнее запрашивать их у BIOS и сверять (см. `docs/part2/bios_doc.txt`,
~строка 1033).
---
## 4. Преимущества
1. **Скорость без wait-state.** Главное и единственное предназначение — код и
данные исполняются на полной частоте 21 МГц без тактов ожидания, в отличие от
основного DRAM.
2. **Идеально для горячих участков.** Внутренние циклы, lookup-таблицы,
временные буферы рендера — то, к чему обращаются интенсивно и многократно.
3. **Отдельный массив.** Не отнимает страницы основного 4 МБ ОЗУ и не пересекается
с видео-областью.
---
## 5. Ограничения и подводные камни ⚠️
Это **самая важная часть** — Fast RAM небезопасна в обращении и легко даёт
«молча не работает».
1. **Акселератор НЕ работает с Fast RAM.**
Акселератор поддерживает пересылку блоков только для основного ОЗУ и
видео-ОЗУ. Пересылку **ROM и FastRAM он не поддерживает**. То есть нельзя
использовать accel-Fill/Copy для заполнения или копирования в/из Fast RAM —
только обычные `LD`-циклы процессора.
2. **Содержимое не сохраняется между процессами.**
Fast RAM может быть использована другими программами. При запуске любого
процесса через DSS (а также самим механизмом переконфигурирования ППЛМ)
**содержимое Fast RAM может быть затёрто**. Нельзя рассчитывать на
персистентность данных между вызовами системы.
3. **Перед вызовами DSS и BIOS Fast RAM надо ОТКЛЮЧАТЬ.**
Системные функции рассчитывают на стандартную карту памяти (ПЗУ в окне 0).
Вызывать `RST 10h` (ESTEX/DSS) или `RST 8` (BIOS) при включённой Fast RAM в
окне 0 — нельзя.
4. **Прерывания.**
Fast RAM (способ A) подключается в окно 0, перекрывая ПЗУ и системный вектор.
Если используются прерывания, программа **обязана установить свой обработчик
по адресу `#0038`**. На практике работу с Fast RAM ведут с `DI`, а на время
ожидания кадра/`halt` Fast RAM временно выключают и восстанавливают (см. §6).
5. **Окно 0 занято под DSS.**
В нашем C-toolchain'е окно 0 (`#0000..#3FFF`) — это ESTEX/DSS система
(см. `release_docs/ru/platform_reference.md`). Подключение Fast RAM в окно 0
вытесняет именно её, что усиливает требование п.3.
6. **Конфликт `#FB` с COVOX.** См. §3, способ A.
---
## 6. Канонический паттерн temporary-off / restore
Из реального резидента (`docs/samples/sprinterIntLib.asm`): перед `ei: halt`
(ожидание кадрового прерывания) Fast RAM временно выключается, после —
восстанавливается прежнее состояние:
```asm
_intWaitVsyncSys
call memCacheOffTemporary ; временно выключаем Fast RAM
ei
halt
jp memCacheRestoryState ; восстанавливаем прежнее состояние подключения
```
Идея паттерна: библиотека хранит флаг «было ли Fast RAM включено», умеет
безопасно его снять на время системных операций (прерывания, DSS/BIOS) и вернуть
обратно. При интеграции в C-toolchain эту логику следует обернуть так же:
сохранять состояние, отключать вокруг любого `RST`/`halt`, восстанавливать.
---
## 7. Выводы для нашего C-toolchain (SDCC + target-слой)
* **Из коробки сейчас не используется.** В `runtime/`, `lib/`, `libc/` обращений
к Fast RAM нет (порт `#FB`/`#7B` нигде не задействован под эту задачу).
* **Где могло бы пригодиться:** разместить «горячую» функцию или таблицу в
Fast RAM для ускорения. Но 64 КБ перекрывают окно 0, конфликтуют с DSS и не
переживают системные вызовы — это узкоспециализированный, ручной режим, не
кандидат на общий механизм линковки.
* **Реалистичный сценарий:** короткий самодостаточный inner-loop без вызовов
системы, с `DI`, со своим вектором `#0038`, скопированный в Fast RAM обычным
`LD`-циклом (не акселератором), исполняемый из окна 0, с гарантированным
восстановлением карты памяти перед любым `RST`.
* **Несовместимость с акселератором** означает, что для графики/блочных операций
Fast RAM бесполезна — там выигрывает accel по основному/видео-ОЗУ.
Если будем добавлять поддержку — делать это отдельным opt-in механизмом
(по аналогии с banked-режимами), с обязательной обёрткой off/restore вокруг всех
точек входа в систему.
+284
View File
@@ -0,0 +1,284 @@
Функция puts()
Функция puts() записывает символьную строку в стандартный
поток данных (т.е. выводит ее на экран). Функция puts()
возвращает код символа «\п».
int puts(const char *string);
После выполнения функции puts() курсор переводится на
новую строку.
Функция putchar()
Функция putchar() записывает символ в стандартный поток
данных (т.е. выводит его на экран). Функция putchar() возвращает
выведенный на экран символ.
int putchar(int ch);
Функция gets()
Функция gets() считывает символьную строку стандартного
входного потока и помещает ее по адресу, заданному указателем
buffer; прием строки заканчивается, если функция обнаруживает
символ конца строки «\п», данный символ удаляется и
заменяется нуль-терминатором «\0».
char *gets (char*buffer);
Функция gets() возвращает указатель на считанную строку.
Функция getchar()
Функция getchar() считывает символ из стандартного
входного потока.
int getchar(void);
Функция getchar() возвращает считанный символ.
=== Функции консольного ввода
char *cgets(char *str)
- помещает в буфер, на начало которого
указывает str, строку символов со стандартного ввода.
Запись символов начинается с str[l]; str[0] должен содержать
максимальное число символов, которое должно быть прочитано
и записано в строку. Функция возвращает указатель на начало
буфера str.
int getch(void)
- выполняет ввод символа с клавиатуры.
Turbo С не выполняет «эхо» ввода. В этой связи полезна для
организации интерфейса с пользователем, при котором нажатие
той или иной клавиши вызывает немедленную реакцию программы
без отображения введённого символа на экране.
int getche(void)
- выполняет небуферизуемый ввод символа
с клавиатуры. Turbo С «эхоирует» ввод на экране. Перевод
строки происходит при достижении правой вертикальной
границы текущего активного окна.
int kbhit(void)
- проверяет, пуст ли буфер клавиатуры.
Если в буфере есть символы, функция возвращает ненулевое
значение, в противном случае она возвращает О. Является
удобным средством предотвращения «зацикливания» или «по-
висания» при ожидании невозможного в данный момент события.
Кроме того, осуществляется проверка нажатия комбинации
клавиш «Ctrl-Break», что позволяет выполнить аварийное завершение
программы.
int ungetch(int ch)
- записывает непосредственно в буфер
клавиатуры символ ch. Он будет доступен при выполнении следующей
операции чтения с консоли (функциями файла
«conio.h»). Разрешает помещать только один символ, который
не должен совпадать с константой EOF, описанной в файле
«stdio.h». В случае успеха функция возвращает ch; в противном
случае возвращается -1.
=== Функции консольного вывода
void textmode(int newmode)
- изменяет текущий текстовый
режим. Новый режим указывается единственным параметром
newmode и может задаваться либо числом, либо с использованием
символических констант, значения которых определяет
перечислимый тип text_modes
Функции консольного вывода используют понятие активного
окна экрана. Активное окно - это прямоугольная область
экрана, в границах которой в данный момент работают функции.
Описание активного окна (или, как часто говорят, фрейм)
хранится во внутренней структурной переменной Turbo С. Установку
параметров активного текстового окна выполняет функция
window ().
void window(int l_t_col, int l_t_row, int r_b_col, int r_b_row)
- описывает активное текстовое окно: первая пара
аргументов задает столбец и строку левого верхнего угла, вторая
пара - правого нижнего угла. Строки и столбцы нумеруются,
начиная от 1. Поэтому, например, координаты левого верх-
него и правого нижнего углов экрана в режимах «25 строк х 80
столбцов» задаются парами (1,1) и (80,25). Ось X направлена
слева направо, а ось Y направлена сверху вниз. Следует обратить
внимание на то, как в Turbo С задаются координаты углов,
сначала столбец, затем строка.
Фрейм окна Turbo С имеет следующую структуру:
struct text_info {
unsigned char winleft; /* столбец, строка */
unsigned char wintop; /* левого верхнего угла */
unsigned char winright; /* столбец, строка */
unsigned char winbottom;/* правого верхнего угла */
unsigned char attribute; /* атрибуты */
unsigned char normattr; /* окна */
unsigned char screenheight; /* полная высота экрана */
unsigned char screenwidth; /* полная ширина экрана */
unsigned char curx; /* строка, столбец */
unsigned char сuгу /* текущей позиции курсора */
}
void gettextinfo(struct text_info *r)
- заполняет поля
структурной переменной по шаблону text_info, на которую
ссылается. Шаблон структуры text_info, описывающей текущее
окно экрана, содержится в заголовочном файле «conio.h».
Функция window() инициализирует поля координат фрейма
окна. Функции textcolor(), textbackground(), textattr() и
другие управляют цветом отображаемых символов окна.
void textattr(int newattr)
- устанавливает атрибут для
функций, работающих с текстовыми окнами. Атрибут хранится в
поле attribute структурной переменной по шаблону text_info,
доступной через функцию gettextinfo()
void textcolor(int newcolor)
- задает цвет символов, не
затрагивая установленный цвет фона. Цвет может быть или числом,
или формироваться из символических констант, значения
которых определяет перечисляемый тип COLORS.
void textbackground(int newcolor)
- задает цвет фона
символов, не затрагивая установленный цвет символа. Цвет может
быть или числом, или формироваться из символических
констант
void gotoxy(int х, int у)
- устанавливает курсор в строку
у и столбец х в текущем активном окне экрана. Верхний левый
угол окна имеет координаты (1,1). При попытке позиционировать
курсор за границы окна он останавливается на границе окна.
Особенностью функции является то, что координаты х и у
являются относительными, приведенными к левому верхнему
углу. Например, если текущее окно было описано функцией
window(1,8,80,25), обращение gotoxy(5,5); установит курсор
в пятый относительный столбец окна (совпадает с абсолютным
столбцом 4, отсчитываемым от О) в пятой относительной строке
(так как верхняя строка окна задана равной 5, то абсолютная
строка будет равна 5+8-1, если отсчет строк ведется от О)
int wherex(void),
int wherey(void)
- сообщают столбец и
строку текущей позиции курсора; возвращают целое число в
диапазоне
void clreol(void)
- стирает в текстовом окне строку, на которую
установлен курсор, начиная с текущей позиции курсора и
до конца строки (до правой вертикальной границы окна).
void clrscr(void)
- очищает все текстовое окно. Цвет «заливки»
окна при очистке будет соответствовать значению, установленному
символической переменной attribute в описании
окна (структурная переменная по шаблону text_info).
void delline(void)
- стирает в текстовом окне всю строку
текста, на которую установлен курсор.
void insline(void)
- вставляет пустую строку в текущей
позиции курсора со сдвигом всех остальных строк окна на одну
строку вниз. При этом самая нижняя строка текста окна теряется.
int cprintf(const char *format, ...)
- выполняет вывод
информации с преобразованием по заданной форматной строке,
на которую указывает format. Является аналогом функции
стандартной библиотеки printf(), но выполняет вывод в пределах
заданного окна. В отличие от printf() функция cprintf()
иначе реагирует на специальный символ '\п' - курсор переводится
на новую строку, но не возвращается к левой границе окна.
Поэтому для перевода курсора на начало новой строки текстового
окна следует вывести последовательность символов CR-
LF (OxOd,OxOa). Остальные специальные символы воздействуют
на курсор так же, как и в случае функций стандартного ввода-
вывода. Функция возвращает число выведенных байтов, а не
число обработанных полей, как это делает функция printf().
int cputs(const char *str)
- выводит строку символов в
текстовое окно, начиная с текущей позиции курсора. На начало
выводимой ASCIIZ-строки указывает str. Является аналогом
функции стандартной библиотеки puts(), выполняет вывод в
пределах заданного окна и при выводе не добавляет специальный
символ '\п'. Реакция cputs() на специальный символ '\п'
аналогична реакции cprintf(): курсор переводится на новую
строку, но не возвращается к левой границе окна. Поэтому для
перевода курсора на начало новой строки текстового окна следует
вывести последовательность символов CR-LF (OxOd,OxOa).
Остальные специальные символы воздействуют на курсор так
же, как и в случае функций стандартного ввода/вывода. Функция
возвращает ASCII-код последнего выведенного на экран
символа. В отличие от puts() в функции отсутствует возврат
символа EOF (вывод на экран происходит в любом случае).
int movetext(int left, int top, int right, int bottom, int destleft, int desttop)
- переносит окно, заданное координатами
левого верхнего (left, top) и правого нижнего (right, bottom)
углов, в другое место на экране, заданное координатами левого
верхнего угла нового положения окна. Размеры окна по горизонтали
и вертикали сохраняются. Все координаты задаются относительно
координат верхнего левого угла экрана (1,1). Функция
возвращает ненулевое значение, если перенос заданного
окна выполнен. В противном случае возвращается О. Функция
корректно выполняет перекрывающиеся переносы, т.е. переносы,
в которых прямоугольная область-источник и область, в которую
окно переносится, частично покрывают друг друга.
int putch(int ch)
- выводит символ в текущей позиции
текстового окна экрана. Как и для функций cprintf(), cputs(),
специальный символ '\п' вызывает только переход курсора на
новую строку текстового окна без возврата к его левой вертикальной
границе. Остальные специальные символы воздействуют
на курсор так же, как и для функций стандартного ввода-
вывода.
int puttext(int left, int top, int right, int bottom, void source)
- выводит на экран текстовое окно, заданное координатами
левого верхнего (left, top) и правого нижнего (right,
bottom) углов. Символы и атрибуты располагаются в буфере,
адрес начала которого задаёт указатель source (функция «открывает»
или «восстанавливает» текстовое окно экрана). Обычно
используется вместе с функцией gettext(), выполняющей
обратную операцию - запись в source символов/атрибутов,
полностью описывающих все знакоместа текстового окна. Функция
проверяет по заданным координатам окна, можно ли разместить
окно на экране для текущего режима видеоадаптера и
корректны ли эти координаты. В случае, когда окно успешно
выведено, возвращается ненулевое значение.
int gettext(int left, int top, int right, int bottom, void destin)
- записывает в буфер destin символы и атрибуты текстового
окна, заданного строкой и столбцом левого верхнего
(left, top) и правого нижнего (right, bottom) углов. Первые два
слова буфера занимают ширина и длина скопированного окна.
Работает только в текстовых режимах видеоадаптера. Координаты
задаются относительно верхнего левого угла экрана (1,1). В
случае успеха возвращает ненулевое число.
=== Файловый ввод/вывод
Прототипы функций ввода-вывода и используемые для этого
типы данных описаны в стандартном заголовочном файле
«stdio.h».
Для файлового ввода/вывода в Си предусмотрены две основные
группы функций:
• функции низкоуровневого ввода/вывода, использующие
для доступа к файлам целочисленные файловые дескрипторы;
• функции более высокого уровня, осуществляющие буферизованный
ввод/вывод с применением потоков.
Поток в Си - это объект, служащий для доступа к файлам
как к упорядоченной последовательности символов.
Поток представляется структурой типа FILE, с которой ассоциирован
некоторый открытый файл. При необходимости несколько
потоков могут ссылаться на один и тот же файл.