Обновить ридми после русификации имен скриптов

This commit is contained in:
mzhoot 2026-06-20 09:16:31 +03:00
parent b0fa390abb
commit ccfe0f7a05

109
README.md
View file

@ -3,6 +3,8 @@
**КВС** — это экспериментальный ассемблер для архитектуры x86-64, полностью использующий **русскую лексику** для мнемоник инструкций, имён регистров и директив. Проект носит образовательный характер и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код. **КВС** — это экспериментальный ассемблер для архитектуры x86-64, полностью использующий **русскую лексику** для мнемоник инструкций, имён регистров и директив. Проект носит образовательный характер и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код.
---
## 📋 Оглавление ## 📋 Оглавление
- [Особенности](#-особенности) - [Особенности](#-особенности)
@ -20,6 +22,8 @@
- [План развития](#-план-развития) - [План развития](#-план-развития)
- [Лицензия](#-лицензия) - [Лицензия](#-лицензия)
---
## ✨ Особенности ## ✨ Особенности
- **Полностью русский синтаксис** — все инструкции, регистры и директивы на кириллице - **Полностью русский синтаксис** — все инструкции, регистры и директивы на кириллице
@ -36,6 +40,8 @@
- **Автоматическая система регрессионного тестирования** — 9+ тестов, проверяющих все аспекты работы ассемблера - **Автоматическая система регрессионного тестирования** — 9+ тестов, проверяющих все аспекты работы ассемблера
- **Минимализм зависимостей** — только стандартная библиотека Python - **Минимализм зависимостей** — только стандартная библиотека Python
---
## 🏗 Архитектура ## 🏗 Архитектура
Процесс трансляции исходного кода `.квс` в исполняемый файл `.elf` проходит через **6 этапов**: Процесс трансляции исходного кода `.квс` в исполняемый файл `.elf` проходит через **6 этапов**:
@ -43,26 +49,26 @@
``` ```
Исходный файл (.квс) Исходный файл (.квс)
│ │
▼ (kvs_lexer.py) ← лексический анализ ▼ (квс_лексер.py) ← лексический анализ
Файл токенов (.токены) Файл токенов (.токены)
│ │
▼ (kvs_parser.py) ← синтаксический анализ ▼ (квс_парсер.py) ← синтаксический анализ
AST-представление (.аст) AST-представление (.аст)
│ │
▼ (kvs_pass1.py) ← ПРОХОД 1: генерация CSV с заглушками (0xCC) ▼ (квс_проход1.py) ← ПРОХОД 1: генерация CSV с заглушками (0xCC)
CSV-файл (.csv) ← содержит все байты программы, метки, виртуальные адреса 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) ELF-файл (.elf)
│ │
▼ ▼
@ -84,20 +90,20 @@ ELF-файл (.elf)
| Файл | Назначение | | Файл | Назначение |
|------|-------------| |------|-------------|
| `kvs_build.py` | Главный сборочный скрипт | | `квс_сборка.py` | Главный сборочный скрипт |
| `kvs_lexer.py` | Лексический анализ | | `квс_лексер.py` | Лексический анализ |
| `kvs_parser.py` | Синтаксический анализ, построение AST | | `квс_парсер.py` | Синтаксический анализ, построение AST |
| `kvs_data.py` | Общие данные: регистры, таблица инструкций | | `kvs_data.py` | Общие данные: регистры, таблица инструкций |
| `kvs_encoder.py` | Фасад кодировщика | | `kvs_encoder.py` | Фасад кодировщика |
| `kvs_encoder_fixsize.py` | Кодировщик инструкций фиксированного размера | | `kvs_encoder_fixsize.py` | Кодировщик инструкций фиксированного размера |
| `kvs_encoder_mutsize.py` | Кодировщик инструкций переменного размера | | `kvs_encoder_mutsize.py` | Кодировщик инструкций переменного размера |
| `kvs_pass1.py` | Генерация CSV с заглушками | | `квс_проход1.py` | Генерация CSV с заглушками |
| `kvs_pass2.py` | Разрешение меток | | `квс_проход2.py` | Разрешение меток |
| `kvs_pass3.py` | Подстановка констант | | `квс_проход3.py` | Подстановка констант |
| `kvs_pass4.py` | Перекодирование инструкций | | `квс_проход4.py` | Перекодирование инструкций |
| `kvs_pass5.py` | Генерация таблиц секций | | `квс_проход5.py` | Генерация таблиц секций |
| `kvs_pass6.py` | Сортировка CSV | | `квс_проход6.py` | Сортировка CSV |
| `kvs_builder.py` | Сборка ELF из CSV | | `квс_финсбор.py` | Сборка ELF из CSV |
### Структура CSV-файла ### Структура CSV-файла
@ -114,6 +120,8 @@ ELF-файл (.elf)
| `рассчитанный_уводящий_адрес` | Реальный адрес метки после разрешения | | `рассчитанный_уводящий_адрес` | Реальный адрес метки после разрешения |
| `рассчитанный_байт` | Итоговый байт после перекодирования | | `рассчитанный_байт` | Итоговый байт после перекодирования |
---
## 🔧 Установка ## 🔧 Установка
```bash ```bash
@ -122,12 +130,14 @@ git clone https://github.com/artradeskz/kvs.git
cd kvs cd kvs
# Установка прав на выполнение # Установка прав на выполнение
chmod +x kvs_build.py chmod +x квс_сборка.py
# Проверка работы # Проверка работы
python3 kvs_build.py --help python3 квс_сборка.py --help
``` ```
---
## 🚀 Быстрый старт ## 🚀 Быстрый старт
### 1. Создайте файл `hello.квс`: ### 1. Создайте файл `hello.квс`:
@ -156,7 +166,7 @@ msg: .строка "Привет мир!\n"
### 2. Скомпилируйте: ### 2. Скомпилируйте:
```bash ```bash
python3 kvs_build.py hello.квс python3 квс_сборка.py hello.квс
``` ```
### 3. Запустите: ### 3. Запустите:
@ -171,6 +181,8 @@ python3 kvs_build.py hello.квс
Привет мир! Привет мир!
``` ```
---
## 🧪 Система тестирования ## 🧪 Система тестирования
Проект включает автоматическую систему регрессионного тестирования, которая проверяет все аспекты работы ассемблера. Проект включает автоматическую систему регрессионного тестирования, которая проверяет все аспекты работы ассемблера.
@ -193,7 +205,7 @@ python3 kvs_build.py hello.квс
├── тест_адресации2/ # абсолютная адресация по метке ├── тест_адресации2/ # абсолютная адресация по метке
├── тест_адресации3/ # косвенная адресация через RBX ├── тест_адресации3/ # косвенная адресация через RBX
├── тест_бнд/ # проверка BSS секции (.bss) ├── тест_бнд/ # проверка BSS секции (.bss)
└── ... └── ...
``` ```
### Запуск тестов ### Запуск тестов
@ -226,6 +238,8 @@ python3 тесты/kvs_full_test.py
| `тест_адресации3` | Косвенную адресацию через RBX | | `тест_адресации3` | Косвенную адресацию через RBX |
| `тест_бнд` | BSS секцию: NOBITS, размер, p_memsz | | `тест_бнд` | BSS секцию: NOBITS, размер, p_memsz |
---
## 📝 Синтаксис ## 📝 Синтаксис
### Структура программы ### Структура программы
@ -271,13 +285,15 @@ _start: ; метка _start
; Косвенная адресация через регистр ; Косвенная адресация через регистр
переместить_имм рбикс, переменная переместить_имм рбикс, переменная
загрузить раикс, [рбикс] загрузить раикс,[рбикс]
; Работа с BND-секцией ; Работа с BND-секцией
.бнд .бнд
счётчик: .байт 0 счётчик: .байт 0
``` ```
---
## 📖 Система команд ## 📖 Система команд
### Загрузка констант ### Загрузка констант
@ -352,6 +368,8 @@ _start: ; метка _start
вызов_системы вызов_системы
``` ```
---
## 💾 Регистры процессора ## 💾 Регистры процессора
КВС поддерживает все основные 64-битные регистры x86-64: КВС поддерживает все основные 64-битные регистры x86-64:
@ -367,6 +385,8 @@ _start: ; метка _start
| `рсиай` | `есиай` | `эс` | `сил` | | `рсиай` | `есиай` | `эс` | `сил` |
| `рдиай` | `едиай` | `ди` | `дил` | | `рдиай` | `едиай` | `ди` | `дил` |
---
## 🔧 Директивы ассемблера ## 🔧 Директивы ассемблера
| Директива | Назначение | Пример | | Директива | Назначение | Пример |
@ -384,6 +404,8 @@ _start: ; метка _start
| `.рездс` | Резервирование двойных слов в BND | `.рездс 25` | | `.рездс` | Резервирование двойных слов в BND | `.рездс 25` |
| `.резкс` | Резервирование квадрослов в BND | `.резкс 10` | | `.резкс` | Резервирование квадрослов в BND | `.резкс 10` |
---
## 📝 Примеры программ ## 📝 Примеры программ
### Работа с памятью (переменные) ### Работа с памятью (переменные)
@ -505,44 +527,46 @@ _start:
.глобал _start .глобал _start
_start: _start:
сравнить_с рдиай, 2 сравнить_с рдиай,2
переход_если_не_равно no_arg переход_если_не_равно no_arg
загрузить р8, [рсиай + 8] загрузить р8,[рсиай + 8]
переместить рдиай, р8 переместить рдиай, р8
исключающее_или рдикс, рдикс исключающее_или рдикс, рдикс
strlen: strlen:
загрузить ал, [р8] загрузить ал,[р8]
сравнить_с ал, 0 сравнить_с ал,0
переход_если_равно strlen_done переход_если_равно strlen_done
увеличить р8 увеличить р8
увеличить рдикс увеличить рдикс
переход strlen переход strlen
strlen_done: strlen_done:
переместить_имм раикс, 1 переместить_имм раикс,1
переместить рсиай, рдиай переместить рсиай, рдиай
переместить_имм рдиай, 1 переместить_имм рдиай,1
вызов_системы вызов_системы
исключающее_или рдиай, рдиай исключающее_или рдиай, рдиай
переместить_имм раикс, 60 переместить_имм раикс,60
вызов_системы вызов_системы
no_arg: no_arg:
переместить_имм раикс, 1 переместить_имм раикс,1
переместить_имм рдиай, 1 переместить_имм рдиай,1
переместить_имм рсиай, msg_no_arg переместить_имм рсиай, msg_no_arg
переместить_имм рдикс, 26 переместить_имм рдикс,26
вызов_системы вызов_системы
переместить_имм рдиай, 1 переместить_имм рдиай,1
переместить_имм раикс, 60 переместить_имм раикс,60
вызов_системы вызов_системы
.данные .данные
msg_no_arg: .строка "Ошибка не передан аргумент\n" msg_no_arg: .строка "Ошибка не передан аргумент\n"
``` ```
---
## 🐛 Отладка и проверка ## 🐛 Отладка и проверка
### Просмотр сгенерированного кода ### Просмотр сгенерированного кода
@ -583,6 +607,8 @@ gdb ./программа.elf
(gdb) stepi (gdb) stepi
``` ```
---
## ⚠️ Ограничения ## ⚠️ Ограничения
### Поддерживается ### Поддерживается
@ -613,10 +639,14 @@ gdb ./программа.elf
- Многомодульная компиляция - Многомодульная компиляция
- Макросы - Макросы
---
## Инструменты разработчика ## Инструменты разработчика
**Подсветка синтаксиса для VS Code** — доступно расширение [Universal Assembly Syntax Highlighting](https://github.com/artradeskz/Universal-Assembly-Syntax-Highlighting) с поддержкой языка КВС (русские инструкции, регистры, секции и директивы) **Подсветка синтаксиса для VS Code** — доступно расширение [Universal Assembly Syntax Highlighting](https://github.com/artradeskz/Universal-Assembly-Syntax-Highlighting) с поддержкой языка КВС (русские инструкции, регистры, секции и директивы)
---
## 📈 План развития ## 📈 План развития
### Реализовано (v2.0) ### Реализовано (v2.0)
@ -630,6 +660,7 @@ gdb ./программа.elf
- Секция `.бнд` для неинициализированных данных - Секция `.бнд` для неинициализированных данных
- Автоматическая система регрессионного тестирования (9+ тестов) - Автоматическая система регрессионного тестирования (9+ тестов)
- Полная совместимость со стандартным toolchain Linux - Полная совместимость со стандартным toolchain Linux
- Русификация основных скриптов сборки
### В планах (v3.0) ### В планах (v3.0)
@ -637,12 +668,16 @@ gdb ./программа.elf
- Сложная адресация с индексом `[reg + reg*scale]` - Сложная адресация с индексом `[reg + reg*scale]`
- Полная SIB-адресация `[reg + reg*scale + disp]` - Полная SIB-адресация `[reg + reg*scale + disp]`
- Стандартная библиотека (`libkvs.квс`): malloc, free, strlen, strcmp, print - Стандартная библиотека (`libkvs.квс`): malloc, free, strlen, strcmp, print
- Полная русификация всех модулей (включая кодировщики)
---
## 📄 Лицензия ## 📄 Лицензия
Только для образовательных целей. Используйте на свой страх и риск. Только для образовательных целей. Используйте на свой страх и риск.
--- ---
*КВС Ассемблер | Экспериментальный проект | 2026* *КВС Ассемблер | Экспериментальный проект | 2026*
*Только для образовательных целей. Используйте на свой страх и риск.* *Только для образовательных целей. Используйте на свой страх и риск.*
``` ```