Tolik-Trek/Estex-DSS
1
0
Fork 0
mirror of https://github.com/Tolik-Trek/Estex-DSS.git synced 2026-08-05 01:34:39 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
c13cd7f67e
Estex-DSS/AGENTS.md
Tolik Trek c13cd7f67e kimi ai test
2026-07-20 16:38:16 +10:00

16 KiB
Raw Blame History

AGENTS.md — Estex DSS

Документ для ИИ-агентов, работающих с этим репозиторием. Описывает устройство проекта, сборку, соглашения и подводные камни. Всё нижесказанное проверено по содержимому репозитория.

1. Обзор проекта

Estex DSS — доработка дисковой операционной системы DSS (Disk SubSystem) для компьютера Sprinter 2000 (SP2000) — российского ZX Spectrum-совместимого компьютера фирмы Peters Plus на процессоре Z84C15 (Z80-совместимый, со встроенным SIO/CTC). Исходный код унаследован от оригинальной DSS от Peters Plus (автор DNS — Denis Parinov, 1998–2003) и развивается дальше (правки BAO и др., актуальная версия — DSS 1.71.x).

Весь код — Z80-ассемблер для sjasmplus. Комментарии и документация — на русском языке. Загрузочная цепочка: BIOS (≥3.06) → boot-сектор (DSSloader.bin) → ядро SYSTEM.DOS → командный интерпретатор SYSTEM.EXE.

Проект собирает три системных файла:

Файл Источник Назначение
SYSTEM.DOS DSS/DSS-MAIN.ASM Ядро DSS (API, файловые системы, драйверы)
SYSTEM.EXE SHELL/SHELL.ASM Командный интерпретатор (шелл)
SYS.EXE BOOT/boot.asm Установщик boot-загрузчика и системных файлов на диск
DSSloader.bin BOOT/DSSBOOT.ASM Сам boot-загрузчик (секторный, ORG #8000)

2. Структура репозитория

  • DSS/ — ядро системы:
    • DSS-MAIN.ASM — точка входа сборки ядра: RST-векторы, таблица функций DSS_API_TABLE, карта буферов CORE_BUFFERS, подключает все модули через INCLUDE.
    • API.asm — агрегатор, включает API/*.asm (~50 файлов — по одному системному вызову на файл: Open.asm, Read.asm, ChDir.asm и т.д.).
    • DOS_FS.ASM — файловые/каталожные процедуры DOS-уровня.
    • Procedures.asm — общие помощники (PUTCHAR, MK_TIME и др.).
    • KEYINTER.ASM — клавиатурный драйвер (PS/2-хост на SIO канала A Z84C15), обрабатывается в прерывании RST 38.
    • DRV-MAIN.ASM — страница драйверов (компилируется в отдельный блок через DISP/ENT в конце DSS-MAIN.ASM), своя таблица RST по #A0000+.
    • FS/ — файловые системы: FS.ASM (диспетчер по сигнатуре #AA55), FAT.asm (FAT12/16/32), CDFS.ASM (CD, в разработке — ветка beta_cdfs).
    • drivers/ — драйверы устройств: media/ (ata_atapi-drv, fdd-drv, ram_disk-drv, ATAPI/CDX), Input/ (MOUSE.ASM).
    • first_init.asm — код первой инициализации (затирается после старта).
    • defines.inc — compile-time флаги ядра (мышь, клавиатура, память и т.п.).
    • VERSION.INC — версия ядра + Lua-логика номера билда.
    • build.txt — счётчик билда ядра (одно число, сейчас 6).
    • DSS_API.TXT — полное описание системных вызовов (UTF-8).
    • DSS_MAP.TXT — карта памяти ядра; KNOWN.BUG, ToDo.txt, CHANGES.LOG — известные баги, планы, история изменений.
  • SHELL/ — командный интерпретатор:
    • SHELL.ASM — точка входа, EXEC.ASM — разбор и выполнение команд, BATCH.ASM — парсер .BAT (%VAR%, %0..%9, GOTO/IF), EDLINE.ASM — редактор строки с историей.
    • Commands/ — по файлу на команду: CD/CHDIR, CLS, DATE, DEL, DIR, ECHO, EXIT, GOTO, HELP, IF, INFO, MD/MKDIR, PATH, PAUSE, REM, REN, RD/RMDIR, SET, VER, REBOOT, BREAK.
    • Procedures/ — print, parsers, math, shared. Messages/main_txt.asm — тексты сообщений.
    • version.inc, build.txt — версия и счётчик билда шелла.
    • README.txt — описание команд и клавиш истории (CP866).
  • BOOT/ — boot.asm (установщик → SYS.EXE), DSSBOOT.ASM (boot-сектор → Build/DSSloader.bin), README.TXT (CP866).
  • Shared_Includes/ — git-подмодуль (ветка main, относительный URL ../Shared_Includes.git, содержит собственный .git):
    • constants/ — SP2000.inc (порты/железо Sprinter), BIOS_equ.inc, dss_equ.inc (номера функций DSS), dss_errors.z80, EXE_Header.z80 (512-байтный заголовок EXE), TRDOS/ZX-константы.
    • structures/ — FileSystem.inc, ATA_ATAPI.INC, bmp.inc.
    • macroses/ — macros.z80, accelerator.z80.
    • LUA/Functions.lua — Lua-функции для sjasmplus (increase_build, get_build, Get_date_RU, Get_checksum и др.).
    • Docs/ — справочники: BIOS functions.asm, DSS_1.71_Functions.asm, sp2000.pdf, описание команд Z80.
  • Build/ — выходы сборки (не отслеживается git, .gitignore в проекте нет): DSS/{SYSTEM.DOS,SYSTEM.EXE,SYS.EXE}, листинги *.LST, Variables.inc (экспорт символов через --exp), Original/ — оригинальные бинарники Peters Plus для сравнения, *_dasm.a80 — дизассемблирования.
  • Hidden/ — архивные/справочные исходники (ATAPI, CDX); исключены из поиска VS Code (.vscode/settings.json → search.exclude).
  • TMP_CODE.ASM — временный рабочий файл-черновик (не часть сборки).
  • keys.md — детальный хендофф-документ по клавиатурной подсистеме (KEYINTER.ASM) для ИИ-сессий; полезен как образец глубокого разбора.

3. Сборка

Ассемблер: sjasmplus (проверено: установлен в /c/tools/msys64/usr/local/bin/sjasmplus). Makefile нет — сборка идёт через задачи VS Code (.vscode/tasks.json) или вручную теми же командами. Ключевые флаги: --syntax=afw --fullpath -Wno-shortblock.

Ядро (задача «Build SYSTEM.DOS», проверено — собирается, 0 ошибок):

sjasmplus --nologo --syntax=afw --fullpath --color=on -Wno-shortblock \
  --lst=Build/DSS-MAIN.LST --raw=Build/DSS/SYSTEM.DOS \
  --exp=Build/Variables.inc dss/dss-main.asm

Задача «Build NEW VERSION of SYSTEM.DOS» добавляет --define INCREASE_BUILD — при этом Lua-код в DSS/VERSION.INC инкрементирует DSS/build.txt.

Шелл (задача «Build SYSTEM.EXE», проверено — собирается, 0 ошибок): sjasmplus ... --raw=Build/DSS/SYSTEM.EXE SHELL/SHELL.ASM. Без --define INCREASE_BUILD билд шелла не трогает SHELL/build.txt.

Установщик (задача «Build SYS.EXE», проверено — собирается, 0 ошибок): sjasmplus ... --raw=Build/DSS/SYS.EXE boot/boot.asm.

Особенности сборки:

  • Версия ядра: VERS=1, MODF=71 в DSS/VERSION.INC, билд из DSS/build.txt → строка вида «DSS 1.71.6».
  • sjasmplus исполняет встроенные Lua-блоки (LUA PASS1/LUA ALLPASS … ENDLUA, INCLUDELUA 'Shared_includes/lua/Functions.lua') — через них подставляются дата сборки и номер билда.
  • Пути в INCLUDE относительны корню репозитория — запускать сборку нужно из корня (в задачах cwd = workspaceFolder). Регистр имён (dss/dss-main.asm vs DSS/DSS-MAIN.ASM) в задачах смешанный — на Windows это работает.
  • Включение файлов — текстовое (INCLUDE): модули не компилируются отдельно, всё собирается одним проходом из главного файла. Активно используются MODULE/ENDMODULE, STRUCT/ENDS, DISP/ENT, ASSERT, DISPLAY (смотрите вывод сборки — там карта адресов буферов).

4. Архитектура рантайма

  • Ядро собирается с ORG 0 и живёт на своей странице в слоте 0 (#0000–#3FFF); карта — в DSS/DSS_MAP.TXT. Вызов функций DSS из программ: номер функции в регистре C, RST 10h; ошибки возвращаются по флагу CF (код в A). Пример — в начале DSS/DSS_API.TXT.
  • RST-векторы ядра: RST 00 — возврат из процесса (RETFAR), RST 08 — портал в BIOS, RST 10 — DSS API, RST 18 — портал на страницу драйверов, RST 20 — FS API, RST 30 — мышиный API, RST 38 — обработчик IM1 (клавиатура KEYSCAN → мышь → курсор).
  • Диспетчер RST_10 индексирует DSS_API_TABLE (адреса функций хранятся раздельными байтами: младшие и старшие — двумя блоками).
  • Драйверы (DRV-MAIN.ASM) собираются в отдельный блок в конце образа ядра (через DISP 0 … ENT) и работают на собственной странице; переход между страницами — через порталы RST и PORTAL.*.
  • Формат исполняемых файлов Estex — EXE с 512-байтным заголовком (Shared_Includes/constants/EXE_Header.z80: сигнатура 'EXE', версия, адреса загрузки/старта/стека). Шелл собирается с DEFINE App_EXE_Version 1.
  • Многозадачность: процессы с IX-контекстом, номер таски в (ix-1); подробности — в DSS_API.TXT (функции 41h EXEC, 47h APPINFO и др.).
  • Минимальная версия BIOS: 3.06 (MINIMUM_BIOS_VERSION в defines.inc), проверяется в first_init.asm.

5. Соглашения по коду

  • Кодировка: CP866 (русская DOS), переводы строк CRLF — у почти всех .asm/.inc/.txt. Исключения в UTF-8: DSS/DSS_API.TXT, keys.md, этот файл. При чтении/поиске из Unix-окружения используйте iconv -f CP866 -t UTF-8 и grep -a (grep может считать файлы бинарными). Не перекодируйте файлы — правьте их, сохраняя CP866+CRLF; git config core.autocrlf=true.
  • Отступы — табуляция; колонки: метка: ОПЕРАЦИЯ операнды ; комментарий. Локальные метки — через точку (.loop), модули — MODULE/ENDMODULE.
  • В заголовках файлов — таблица изменений Rev / Date / Name / Description (авторы: DNS, BAO и др.). При существенных правках добавляйте строку туда же в том же формате.
  • Маркеры задач в коде: ;!TODO, ;!FIXIT, ;!HARDCODE, чек-листы [ ] / [x] / [!] (легенда — в DSS/ToDo.txt).
  • Compile-time конфигурация — только через DEFINE в DSS/defines.inc (для ядра) и аналогичных *.inc; закомментированный define = выключено (см. комментарий в начале defines.inc).
  • Новый системный вызов: файл DSS/API/<Name>.asm + include в DSS/API.asm + слот в DSS_API_TABLE + константа в Shared_Includes/constants/dss_equ.inc + описание в DSS/DSS_API.TXT.
  • Новая команда шелла: файл SHELL/Commands/<CMD>.ASM + include в SHELL/SHELL.ASM + регистрация в парсере (EXEC.ASM/BATCH.ASM).
  • Коммит-сообщения — на русском, свободной формы; пометки вида -bug, -bugfix, !FIXIT. Текущая ветка разработки — beta_cdfs.

6. Тестирование и отладка

Автоматических тестов в проекте нет. Проверка — ручная, на эмуляторе или реальном железе:

  • Задача «Copy files to IMG» / «Copy THIS file to Test_2g.img»: hdfmonkey put копирует собранные файлы в HDD-образ C:\tools\Progs\MAME\IMG\test_2g.img (или sp_disk2.img).
  • Задача «Run MAME» запускает эмулятор через внешний .bat (C:\tools\Progs\MAME\*.bat, сами скрипты вне репозитория).
  • Отладка: VS Code + DeZog (.vscode/launch.json, remoteType zsim), использует .sld-файлы sjasmplus; задача «Build this file» собирает текущий файл с --sld для отладчика.
  • Дизассемблирование: задача «Disassemble binary» (z80dasm).
  • Листинг Build/DSS-MAIN.LST (~1 МБ) и вывод DISPLAY при сборке — основной способ контроля адресов/размеров.
  • При сборке с --define INCREASE_BUILD меняются отслеживаемые git'ом файлы */build.txt — не коммитьте случайные инкременты.

7. Безопасность и осторожность

  • Код напрямую программирует железо (OUT в системные порты, переключение страниц памяти, прерывания) — ошибка может подвесить систему только на целевой машине/эмуляторе, но не хост.
  • hdfmonkey put модифицирует файлы-образы дисков — убедитесь, что путь к образу верный, прежде чем запускать задачи копирования.
  • BOOT/boot.asm (SYS.EXE) — программа записи boot-сектора на реальные FDD/HDD; на реальном железе это потенциально деструктивная операция.

8. Известные проблемы (на момент написания)

  • Сборка SYSTEM.EXE сломана — исправлено 2026-07-18 (в рабочем дереве, правка SHELL/version.inc ещё не закоммичена): задвоенные блоки (CONSOLE_VERS/CONSOLE_MODF/CONSOLE_BUILD, лишний LUA ALLPASS) убраны, increase_build вызывается только при --define INCREASE_BUILD. Проверено: шелл собирается с 0 ошибок, SHELL/build.txt не меняется. Исходная поломка была зафиксирована в коммите 32dca48.
  • Актуальные списки багов и планов: DSS/KNOWN.BUG (включая разбор багов от ИИ), DSS/ToDo.txt, DSS/CHANGES.LOG (секции !FIXIT/!TODO).
  • Ветка beta_cdfs — работа над CDFS/BigDir в процессе («Пока не работает, надо доделывать BigDir» — коммит 41ff458).