From ccfe0f7a05e810d03765ddad3d610c11088dfec3 Mon Sep 17 00:00:00 2001 From: mzhoot Date: Sat, 20 Jun 2026 09:16:31 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20=D1=80=D0=B8=D0=B4=D0=BC=D0=B8=20=D0=BF=D0=BE=D1=81?= =?UTF-8?q?=D0=BB=D0=B5=20=D1=80=D1=83=D1=81=D0=B8=D1=84=D0=B8=D0=BA=D0=B0?= =?UTF-8?q?=D1=86=D0=B8=D0=B8=20=D0=B8=D0=BC=D0=B5=D0=BD=20=D1=81=D0=BA?= =?UTF-8?q?=D1=80=D0=B8=D0=BF=D1=82=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 109 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 72 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index c3e473a..0a570c1 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ **КВС** — это экспериментальный ассемблер для архитектуры x86-64, полностью использующий **русскую лексику** для мнемоник инструкций, имён регистров и директив. Проект носит образовательный характер и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код. +--- + ## 📋 Оглавление - [Особенности](#-особенности) @@ -20,6 +22,8 @@ - [План развития](#-план-развития) - [Лицензия](#-лицензия) +--- + ## ✨ Особенности - **Полностью русский синтаксис** — все инструкции, регистры и директивы на кириллице @@ -36,6 +40,8 @@ - **Автоматическая система регрессионного тестирования** — 9+ тестов, проверяющих все аспекты работы ассемблера - **Минимализм зависимостей** — только стандартная библиотека Python +--- + ## 🏗 Архитектура Процесс трансляции исходного кода `.квс` в исполняемый файл `.elf` проходит через **6 этапов**: @@ -43,26 +49,26 @@ ``` Исходный файл (.квс) │ - ▼ (kvs_lexer.py) ← лексический анализ + ▼ (квс_лексер.py) ← лексический анализ Файл токенов (.токены) │ - ▼ (kvs_parser.py) ← синтаксический анализ + ▼ (квс_парсер.py) ← синтаксический анализ AST-представление (.аст) │ - ▼ (kvs_pass1.py) ← ПРОХОД 1: генерация CSV с заглушками (0xCC) + ▼ (квс_проход1.py) ← ПРОХОД 1: генерация CSV с заглушками (0xCC) CSV-файл (.csv) ← содержит все байты программы, метки, виртуальные адреса │ - ▼ (kvs_pass2.py) ← ПРОХОД 2: разрешение меток + ▼ (квс_проход2.py) ← ПРОХОД 2: разрешение меток │ - ▼ (kvs_pass3.py) ← ПРОХОД 3: подстановка констант (.константа) + ▼ (квс_проход3.py) ← ПРОХОД 3: подстановка констант (.константа) │ - ▼ (kvs_pass4.py) ← ПРОХОД 4: перекодирование инструкций + ▼ (квс_проход4.py) ← ПРОХОД 4: перекодирование инструкций │ - ▼ (kvs_pass5.py) ← ПРОХОД 5: генерация корректных таблиц секций для совместимости с toolchain + ▼ (квс_проход5.py) ← ПРОХОД 5: генерация корректных таблиц секций для совместимости с toolchain │ - ▼ (kvs_pass6.py) ← ПРОХОД 6: постобработка CSV для визуального анализа + ▼ (квс_проход6.py) ← ПРОХОД 6: постобработка CSV для визуального анализа │ - ▼ (kvs_builder.py) ← сборка ELF из CSV + ▼ (квс_финсбор.py) ← сборка ELF из CSV ELF-файл (.elf) │ ▼ @@ -84,20 +90,20 @@ ELF-файл (.elf) | Файл | Назначение | |------|-------------| -| `kvs_build.py` | Главный сборочный скрипт | -| `kvs_lexer.py` | Лексический анализ | -| `kvs_parser.py` | Синтаксический анализ, построение AST | +| `квс_сборка.py` | Главный сборочный скрипт | +| `квс_лексер.py` | Лексический анализ | +| `квс_парсер.py` | Синтаксический анализ, построение AST | | `kvs_data.py` | Общие данные: регистры, таблица инструкций | | `kvs_encoder.py` | Фасад кодировщика | | `kvs_encoder_fixsize.py` | Кодировщик инструкций фиксированного размера | | `kvs_encoder_mutsize.py` | Кодировщик инструкций переменного размера | -| `kvs_pass1.py` | Генерация CSV с заглушками | -| `kvs_pass2.py` | Разрешение меток | -| `kvs_pass3.py` | Подстановка констант | -| `kvs_pass4.py` | Перекодирование инструкций | -| `kvs_pass5.py` | Генерация таблиц секций | -| `kvs_pass6.py` | Сортировка CSV | -| `kvs_builder.py` | Сборка ELF из CSV | +| `квс_проход1.py` | Генерация CSV с заглушками | +| `квс_проход2.py` | Разрешение меток | +| `квс_проход3.py` | Подстановка констант | +| `квс_проход4.py` | Перекодирование инструкций | +| `квс_проход5.py` | Генерация таблиц секций | +| `квс_проход6.py` | Сортировка CSV | +| `квс_финсбор.py` | Сборка ELF из CSV | ### Структура CSV-файла @@ -114,6 +120,8 @@ ELF-файл (.elf) | `рассчитанный_уводящий_адрес` | Реальный адрес метки после разрешения | | `рассчитанный_байт` | Итоговый байт после перекодирования | +--- + ## 🔧 Установка ```bash @@ -122,12 +130,14 @@ git clone https://github.com/artradeskz/kvs.git cd kvs # Установка прав на выполнение -chmod +x kvs_build.py +chmod +x квс_сборка.py # Проверка работы -python3 kvs_build.py --help +python3 квс_сборка.py --help ``` +--- + ## 🚀 Быстрый старт ### 1. Создайте файл `hello.квс`: @@ -156,7 +166,7 @@ msg: .строка "Привет мир!\n" ### 2. Скомпилируйте: ```bash -python3 kvs_build.py hello.квс +python3 квс_сборка.py hello.квс ``` ### 3. Запустите: @@ -171,6 +181,8 @@ python3 kvs_build.py hello.квс Привет мир! ``` +--- + ## 🧪 Система тестирования Проект включает автоматическую систему регрессионного тестирования, которая проверяет все аспекты работы ассемблера. @@ -193,7 +205,7 @@ python3 kvs_build.py hello.квс ├── тест_адресации2/ # абсолютная адресация по метке ├── тест_адресации3/ # косвенная адресация через RBX ├── тест_бнд/ # проверка BSS секции (.bss) -└── ... +└── ... ``` ### Запуск тестов @@ -226,6 +238,8 @@ python3 тесты/kvs_full_test.py | `тест_адресации3` | Косвенную адресацию через RBX | | `тест_бнд` | BSS секцию: NOBITS, размер, p_memsz | +--- + ## 📝 Синтаксис ### Структура программы @@ -271,13 +285,15 @@ _start: ; метка _start ; Косвенная адресация через регистр переместить_имм рбикс, переменная -загрузить раикс, [рбикс] +загрузить раикс,[рбикс] ; Работа с BND-секцией .бнд счётчик: .байт 0 ``` +--- + ## 📖 Система команд ### Загрузка констант @@ -352,6 +368,8 @@ _start: ; метка _start вызов_системы ``` +--- + ## 💾 Регистры процессора КВС поддерживает все основные 64-битные регистры x86-64: @@ -367,6 +385,8 @@ _start: ; метка _start | `рсиай` | `есиай` | `эс` | `сил` | | `рдиай` | `едиай` | `ди` | `дил` | +--- + ## 🔧 Директивы ассемблера | Директива | Назначение | Пример | @@ -384,6 +404,8 @@ _start: ; метка _start | `.рездс` | Резервирование двойных слов в BND | `.рездс 25` | | `.резкс` | Резервирование квадрослов в BND | `.резкс 10` | +--- + ## 📝 Примеры программ ### Работа с памятью (переменные) @@ -505,44 +527,46 @@ _start: .глобал _start _start: - сравнить_с рдиай, 2 + сравнить_с рдиай,2 переход_если_не_равно no_arg - загрузить р8, [рсиай + 8] + загрузить р8,[рсиай + 8] переместить рдиай, р8 исключающее_или рдикс, рдикс strlen: - загрузить ал, [р8] - сравнить_с ал, 0 + загрузить ал,[р8] + сравнить_с ал,0 переход_если_равно strlen_done увеличить р8 увеличить рдикс переход strlen strlen_done: - переместить_имм раикс, 1 + переместить_имм раикс,1 переместить рсиай, рдиай - переместить_имм рдиай, 1 + переместить_имм рдиай,1 вызов_системы исключающее_или рдиай, рдиай - переместить_имм раикс, 60 + переместить_имм раикс,60 вызов_системы no_arg: - переместить_имм раикс, 1 - переместить_имм рдиай, 1 + переместить_имм раикс,1 + переместить_имм рдиай,1 переместить_имм рсиай, msg_no_arg - переместить_имм рдикс, 26 + переместить_имм рдикс,26 вызов_системы - переместить_имм рдиай, 1 - переместить_имм раикс, 60 + переместить_имм рдиай,1 + переместить_имм раикс,60 вызов_системы .данные msg_no_arg: .строка "Ошибка не передан аргумент\n" ``` +--- + ## 🐛 Отладка и проверка ### Просмотр сгенерированного кода @@ -583,6 +607,8 @@ gdb ./программа.elf (gdb) stepi ``` +--- + ## ⚠️ Ограничения ### Поддерживается @@ -613,10 +639,14 @@ gdb ./программа.elf - Многомодульная компиляция - Макросы +--- + ## Инструменты разработчика **Подсветка синтаксиса для VS Code** — доступно расширение [Universal Assembly Syntax Highlighting](https://github.com/artradeskz/Universal-Assembly-Syntax-Highlighting) с поддержкой языка КВС (русские инструкции, регистры, секции и директивы) +--- + ## 📈 План развития ### Реализовано (v2.0) @@ -630,6 +660,7 @@ gdb ./программа.elf - Секция `.бнд` для неинициализированных данных - Автоматическая система регрессионного тестирования (9+ тестов) - Полная совместимость со стандартным toolchain Linux +- Русификация основных скриптов сборки ### В планах (v3.0) @@ -637,12 +668,16 @@ gdb ./программа.elf - Сложная адресация с индексом `[reg + reg*scale]` - Полная SIB-адресация `[reg + reg*scale + disp]` - Стандартная библиотека (`libkvs.квс`): malloc, free, strlen, strcmp, print +- Полная русификация всех модулей (включая кодировщики) + +--- ## 📄 Лицензия Только для образовательных целей. Используйте на свой страх и риск. --- + *КВС Ассемблер | Экспериментальный проект | 2026* *Только для образовательных целей. Используйте на свой страх и риск.* -``` +``` \ No newline at end of file