КВС — Ассемблер с русским синтаксисом для x86-64

╔══════════════════════════════════╗
║   ██╗  ██╗  ██╗   ██╗  ███████╗  ║
║   ██║ ██╔╝  ██╗   ██╗  ██╔════╝  ║
║   █████╔╝   ██╗   ██╗  ███████╗  ║
║   ██║╚██╗   ╚██╗ ██╔╝  ╚════██║  ║
║   ██║ ╚██╗    ╚██╔╝    ███████║  ║
║   ╚═╝  ╚═╝     ╚═╝     ╚══════╝  ║
╚══════════════════════════════════╝

Версия 2.0 | Экспериментальный проект | 2026

✓ Абсолютная адресация реализована | ✓ Косвенная адресация реализована | ✓ Секция .bss реализована

┌──[ ОГЛАВЛЕНИЕ ]────────────────────────────────────────────┐

Назначение и концепция
Особенности и возможности
Архитектура и процесс сборки
Установка и запуск
Синтаксис исходных файлов (.квс)
Система команд
Работа с памятью
Регистры процессора
Директивы ассемблера
Примеры программ
Процесс трансляции
Статус реализации
План развития
Ограничения

└──────────────────────────────────────────────────────────────┘

НАЗНАЧЕНИЕ И КОНЦЕПЦИЯ

КВС — это ассемблер для архитектуры x86-64, полностью использующий русскую лексику для мнемоник инструкций, имён регистров и директив. Проект носит образовательный и экспериментальный характер и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код.

Ключевые принципы проекта:

Русскоязычный синтаксис — все инструкции, регистры и директивы на кириллице
Модульная архитектура — лексер, парсер, два прохода, сборщик ELF
Минимализм зависимостей — только стандартная библиотека Python
Подготовка к самокомпиляции — архитектура, допускающая написание компилятора на самом КВС

ОСОБЕННОСТИ И ВОЗМОЖНОСТИ

Полностью русский синтаксис — переместить, прибавить, вызвать, регистры раикс, есипи, ал, директивы .текст, .данные, .бсс
Генерация исполняемых ELF-файлов — 64-битные ELF для Linux, готовые к запуску
Двухпроходная сборка — традиционная схема с разрешением меток
Поддержка секций — разделение на .текст (код), .данные (инициализированные данные) и .бсс (неинициализированные данные)
Полная адресация памяти:
- Абсолютная адресация по меткам [переменная]
- Абсолютная адресация по числовому адресу [0x402000]
- Косвенная адресация через регистр [раикс]
- Всё с RIP-relative кодированием для 64-битных перемещений
CSV-логирование — детальный файл .csv с соответствием адресов, байтов и исходных команд
Более 50 инструкций — полный набор основных команд x86-64
Рефакторинг — кодогенерация вынесена в отдельный модуль kvs_pass2_encoder.py

АРХИТЕКТУРА И ПРОЦЕСС СБОРКИ

Исходный файл (.квс) │ ▼ (kvs_lexer.py) Файл токенов (.токены) │ ▼ (kvs_parser.py) AST-представление (.аст) │ ▼ (kvs_pass1.py) Первый проход: размеры, метки (.проход1) │ ▼ (kvs_pass2.py + kvs_pass2_encoder.py) Второй проход: генерация кода (.csv) │ ▼ (kvs_builder.py) ELF-компоновщик (.elf) Исполняемый файл!

Модули компилятора

Файл	Назначение
`kvs_build.py`	Главный сборочный скрипт
`kvs_lexer.py`	Лексический анализ, разбор на токены
`kvs_parser.py`	Синтаксический анализ, построение AST
`kvs_pass1.py`	Первый проход: вычисление размеров и адресов меток
`kvs_pass2.py`	Второй проход: обход AST, генерация CSV
`kvs_pass2_encoder.py`	Кодировщик инструкций (все encode_* функции)
`kvs_builder.py`	Сборка ELF-файла из CSV
`kvs_data.py`	Общие данные (регистры, инструкции)

УСТАНОВКА И ЗАПУСК

# Клонирование репозитория
git clone https://github.com/artradeskz/kvs.git
cd kvs

# Установка прав на выполнение (при необходимости)
chmod +x kvs_build.py

# Компиляция программы
python3 kvs_build.py программа.квс

# Запуск скомпилированной программы
./программа.elf

СИНТАКСИС ИСХОДНЫХ ФАЙЛОВ (.квс)

; Комментарий начинается с точки с запятой

.бсс                        ; Начало секции неинициализированных данных
    счётчик: .байт 0        ; Переменная без начального значения

.данные                     ; Начало секции инициализированных данных
    message: .строка_нуль "Привет, мир!"

.текст                      ; Начало секции кода
.глобал _start              ; Точка входа

_start:
    ; Абсолютная адресация через метку
    переместить_имм раикс, 42
    сохранить [счётчик], раикс    ; запись в BSS-переменную
    
    ; Абсолютная адресация через число
    сохранить [0x402000], раикс   ; запись по абсолютному адресу
    
    ; Косвенная адресация через регистр
    переместить_имм рбикс, message
    загрузить раикс, [рбикс]      ; чтение через регистр

    ; Системный вызов write
    переместить_имм раикс, 1
    переместить_имм рсиай, message
    переместить_имм рдикс, 13
    вызов_системы

    ; Выход с кодом из счётчика
    загрузить рдиай, [счётчик]
    переместить_имм раикс, 60
    вызов_системы

СИСТЕМА КОМАНД

Категория	Примеры инструкций	Соответствие NASM
Перемещение данных	`переместить`, `переместить_имм`	`mov`, `mov reg, imm`
Работа с памятью	`загрузить`, `сохранить`, `загрузить_адрес`	`mov reg, mem`, `mov mem, reg`, `lea`
Арифметика	`прибавить`, `вычесть`, `увеличить`, `уменьшить`	`add`, `sub`, `inc`, `dec`
Логические	`сравнить`, `сравнить_с`, `проверить`	`cmp`, `test`
Условные переходы	`переход_если_равно`, `переход_если_больше`, `короткий_переход`	`je`, `jg`, `jmp short`
Безусловные переходы	`переход`, `короткий_переход`	`jmp`, `jmp short`
Системные	`вызов_системы`	`syscall`

РАБОТА С ПАМЯТЬЮ

✓ РЕАЛИЗОВАНО (v2.0): Абсолютная адресация (метки и числа), косвенная адресация через регистры

Поддерживаемые формы:

Синтаксис	Описание	Пример
`[метка]`	Адрес метки (из .данные или .бсс)	`загрузить раикс, [переменная]`
`[число]`	Абсолютный адрес	`сохранить [0x402000], раикс`
`[регистр]`	Косвенная адресация через регистр	`загрузить раикс, [рбикс]`

Пример использования:

.бсс
счётчик: .байт 0
указатель: .байт 0

.данные
переменная: .байт 42
message: .строка_нуль "Hello"

.текст
_start:
    ; Абсолютная адресация через метку
    загрузить раикс, [переменная]
    
    ; Абсолютная адресация через число
    сохранить [0x402000], раикс
    
    ; Косвенная адресация
    переместить_имм рбикс, переменная
    загрузить раикс, [рбикс]
    
    ; Работа с BSS
    сохранить [счётчик], раикс
    
    ; Завершение
    переместить_имм раикс, 60
    загрузить рдиай, [счётчик]
    вызов_системы

📌 ВАЖНО: Все тесты из папки тесты/ успешно собираются и запускаются, включая тест, воспроизводящий баг с BSS-секцией. Адресация работает корректно во всех формах.

РЕГИСТРЫ ПРОЦЕССОРА

64-битные	32-битные	16-битные	8-битные (мл.)
`раикс`	`еаикс`	`аикс`	`ал`
`рбикс`	`ебикс`	`бикс`	`бл`
`рсикс`	`есикс`	`сикс`	`кл`
`рдикс`	`едикс`	`дикс`	`дл`
`рсипи`	`есипи`	`эсп`	`спл`
`рбипи`	`ебипи`	`бипи`	`бпл`
`рсиай`	`есиай`	`эс`	`сил`
`рдиай`	`едиай`	`ди`	`дил`

⚠️ ПРИМЕЧАНИЕ: Старшие 8-битные регистры (AH, BH, CH, DH) и расширенные младшие (SPL, BPL, SIL, DIL) не поддерживаются. Регистры R8–R15 также отсутствуют.

ДИРЕКТИВЫ АССЕМБЛЕРА

Директива	Назначение	Пример
`.текст`	Начало секции кода	`.текст`
`.данные`	Начало секции инициализированных данных	`.данные`
`.бсс`	Начало секции неинициализированных данных	`.бсс`
`.глобал`	Объявление глобальной метки	`.глобал _start`
`.строка`	Строка без нулевого терминатора	`.строка "Hello"`
`.строка_нуль`	Строка с нулевым терминатором	`.строка_нуль "Hello"`
`.байт`	Резервирование байтов	`.байт 0x0A, 255, 0b0001`
`.константа`	Определение константы	`.константа SIZE = 100`

ПРИМЕРЫ ПРОГРАММ

Пример 1: "Привет, мир!"

.глобал _start
.текст

_start:
    ; write(1, msg, 13)
    переместить_имм раикс, 1
    переместить_имм рдиай, 1
    переместить_имм рсиай, msg
    переместить_имм рдикс, 13
    вызов_системы

    ; exit(0)
    переместить_имм раикс, 60
    переместить_имм рдиай, 0
    вызов_системы

.данные
msg: .строка_нуль "Hello, World!"

Пример 2: Работа с BSS-секцией

.глобал _start
.текст

_start:
    ; Инициализация счётчика
    переместить_имм раикс, 0
    сохранить [счётчик], раикс
    
    ; Цикл: увеличить счётчик 10 раз
    переместить_имм рсикс, 10
loop:
    загрузить раикс, [счётчик]
    увеличить раикс
    сохранить [счётчик], раикс
    уменьшить рсикс
    сравнить_с рсикс, 0
    переход_если_больше loop
    
    ; Выход с кодом = значение счётчика
    загрузить рдиай, [счётчик]
    переместить_имм раикс, 60
    вызов_системы

.бсс
счётчик: .байт 0

Пример 3: Косвенная адресация

.глобал _start
.текст

_start:
    ; Загружаем адрес переменной в регистр
    переместить_имм рбикс, переменная
    
    ; Косвенная запись
    переместить_имм раикс, 99
    сохранить [рбикс], раикс
    
    ; Косвенное чтение
    загрузить раикс, [рбикс]
    
    ; Выход
    переместить_имм рдиай, раикс
    переместить_имм раикс, 60
    вызов_системы

.данные
переменная: .байт 0

Пример 4: Абсолютный адрес

.глобал _start
.текст

_start:
    ; Запись по абсолютному адресу 0x402000
    переместить_имм раикс, 0x2A
    сохранить [0x402000], раикс
    
    ; Чтение по абсолютному адресу
    загрузить рбикс, [0x402000]
    
    ; Выход с кодом 42
    переместить_имм раикс, 60
    переместить_имм рдиай, 0x2A
    вызов_системы

ПРОЦЕСС ТРАНСЛЯЦИИ И ВЫХОДНЫЕ ФАЙЛЫ

Запуск ассемблера:

python3 kvs_build.py программа.квс

В результате создаются файлы:

программа.токены — результат лексического анализа
программа.аст — AST-представление
программа.проход1 — результаты первого прохода (размеры, метки)
программа.csv — детальный лог с адресами, байтами и командами
программа.elf — исполняемый ELF-файл

СТАТУС РЕАЛИЗАЦИИ

✅ Полностью реализовано (v2.0)

Лексер с токенами [, ], NUMBER
Парсер с поддержкой операндов в квадратных скобках
Первый проход с корректным расчётом размера инструкций с памятью
Второй проход с кодированием адресации через RIP-relative
Абсолютная адресация по меткам [переменная]
Абсолютная адресация по числовым адресам [0x402000]
Косвенная адресация через регистры [раикс]
Секция .бсс для неинициализированных данных
Рефакторинг: выделение кодировщика в отдельный модуль
Более 50 инструкций x86-64
CSV-логирование

⚠️ Частично реализовано / ограничено

загрузить_адрес (LEA) — только для чисел, не для меток
Старшие 8-битные регистры (AH, BH, CH, DH) не поддерживаются
Регистры R8–R15 не поддерживаются

ПЛАН РАЗВИТИЯ

v2.0 (текущая) — Адресация и BSS

✅ Лексер: [, ], NUMBER
✅ Парсер: [метка], [число], [регистр]
✅ Pass1: корректный расчёт размера инструкций
✅ Pass2: RIP-relative кодирование
✅ Абсолютная адресация (метки и числа)
✅ Косвенная адресация ([reg])
✅ Секция .бсс
✅ Рефакторинг энкодера

v3.0 (планируется) — Расширенная адресация

❌ [reg + disp] — адресация со смещением
❌ [reg + reg*scale] — с индексным регистром
❌ [reg + reg*scale + disp] — полная SIB-адресация
❌ LEA для меток
❌ PUSH/POP/CALL/RET

v4.0 (отложено) — Стандартная библиотека

❌ malloc, free
❌ strlen, strcmp, memcpy
❌ putchar, getchar

ОГРАНИЧЕНИЯ

Адресация со смещением — формы [reg+disp], [reg+reg*scale], [reg+reg*scale+disp] не реализованы
LEA для меток — загрузить_адрес reg, [метка] не работает, используйте переместить_имм reg, метка
Старшие 8-битные регистры — AH, BH, CH, DH не поддерживаются
Расширенные регистры — SPL, BPL, SIL, DIL, а также R8–R15 не поддерживаются
Нет умножения и деления — инструкции MUL/DIV не реализованы
Нет операций со стеком — PUSH/POP/CALL/RET отсутствуют
Нет динамической памяти — нет встроенных malloc/free
Нет макросов и условной компиляции
Экспериментальный статус — некоторые инструкции могут быть реализованы не полностью