administrator/kvs
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

ридми

Browse source
This commit is contained in:
mzhoot 2026-05-02 23:17:09 +03:00
parent 4c5a952bae
commit 520da3a8a3
1 changed files with 220 additions and 252 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

470
README.md
View file

@ -1,52 +1,133 @@
# Документация компилятора КВС ```markdown
# КВС (Компилятор B Семейства) — Ассемблер с русским синтаксисом для x86-64
## 1. Общие сведения [![Version](https://img.shields.io/badge/version-2.0-green.svg)](https://github.com/username/kvs)
[![Python](https://img.shields.io/badge/python-3.6+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
**КВС** (язык программирования) — это низкоуровневый язык, транслируемый в 64-битный ELF-исполняемый файл для архитектуры x86-64. Компилятор написан на Python и состоит из нескольких модулей, выполняющих лексический анализ, синтаксический разбор, двухпроходную генерацию кода и сборку ELF-файла. **КВС** — это экспериментальный ассемблер для архитектуры x86-64, полностью использующий **русскую лексику** для мнемоник инструкций, имён регистров и директив. Проект носит образовательный характер и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код.
### 1.1. Состав компилятора ## 📋 Оглавление
- [Особенности](#-особенности)
- [Архитектура](#-архитектура)
- [Установка](#-установка)
- [Быстрый старт](#-быстрый-старт)
- [Синтаксис](#-синтаксис)
- [Система команд](#-система-команд)
- [Регистры](#-регистры-процессора)
- [Директивы](#-директивы-ассемблера)
- [Примеры программ](#-примеры-программ)
- [Отладка](#-отладка-и-проверка)
- [Ограничения](#-ограничения)
- [Лицензия](#-лицензия)
## ✨ Особенности
- **Полностью русский синтаксис** — все инструкции, регистры и директивы на кириллице
- **Генерация исполняемых ELF-файлов** — 64-битные ELF для Linux, готовые к запуску
- **Двухпроходная сборка** — традиционная схема с разрешением меток
- **Поддержка секций** — разделение на `.текст` (код) и `.данные` (данные)
- **CSV-логирование** — детальный файл с соответствием адресов, байтов и исходных команд
- **Более 50 инструкций** — полный набор основных команд x86-64
- **Минимализм зависимостей** — только стандартная библиотека Python
## 🏗 Архитектура
Процесс трансляции исходного кода `.квс` в исполняемый файл `.elf` проходит через несколько этапов:
```
Исходный файл (.квс)
│
▼ (kvs_lexer.py)
Файл токенов (.токены)
│
▼ (kvs_parser.py)
AST-представление (.аст)
│
▼ (kvs_pass1.py)
Первый проход: размеры, метки (.проход1)
│
▼ (kvs_pass2.py)
Второй проход: генерация кода (.csv)
│
▼ (kvs_builder.py)
ELF-компоновщик (.elf)
Исполняемый файл!
```
### Модули компилятора
| Файл | Назначение | | Файл | Назначение |
|------|------------| |------|------------|
| `kvs_8.py` | Монолитный ассемблер (оригинальная версия) | | `kvs_build.py` | Главный сборочный скрипт |
| `kvs_build.py` | Главный сборочный скрипт, запускающий все этапы |
| `kvs_lexer.py` | Лексический анализ, разбор на токены | | `kvs_lexer.py` | Лексический анализ, разбор на токены |
| `kvs_parser.py` | Синтаксический анализ, построение AST | | `kvs_parser.py` | Синтаксический анализ, построение AST |
| `kvs_pass1.py` | Первый проход: вычисление размеров и адресов меток | | `kvs_pass1.py` | Первый проход: вычисление размеров и адресов меток |
| `kvs_pass2.py` | Второй проход: генерация машинного кода | | `kvs_pass2.py` | Второй проход: генерация машинного кода |
| `kvs_builder.py` | Сборка ELF-файла из CSV-данных | | `kvs_builder.py` | Сборка ELF-файла из CSV |
| `kvs_data.py` | Общие данные (регистры, инструкции, константы) | | `kvs_data.py` | Общие данные (регистры, инструкции) |
### 1.2. Запуск компилятора ## 🔧 Установка
```bash ```bash
# Монолитная версия # Клонирование репозитория
python3 kvs_8.py <файл.квс> git clone https://github.com/username/kvs.git
cd kvs
# Декомпозированная версия # Установка прав на выполнение (при необходимости)
python3 kvs_build.py <файл.квс> chmod +x kvs_build.py
# Проверка работы
python3 kvs_build.py --help
``` ```
Входной файл должен иметь расширение **`.квс`**. ## 🚀 Быстрый старт
### 1.3. Результаты компиляции ### 1. Создайте файл `hello.квс`:
| Файл | Содержимое | ```asm
|------|------------| .текст
| `<имя>.elf` | Исполняемый ELF-файл (64-bit) | .глобал _start
| `<имя>.log.csv` | Лог с адресами, байтами и соответствием командам |
| `<имя>.токены` | Промежуточный файл токенов (только для декомп. версии) |
| `<имя>.аст` | Промежуточный AST-файл (только для декомп. версии) |
| `<имя>.проход1` | Данные первого прохода (только для декомп. версии) |
| `<имя>.csv` | CSV с машинным кодом (только для декомп. версии) |
--- _start:
; write(1, msg, 13)
переместить_имм раикс, 1
переместить_имм рдиай, 1
переместить_имм рсиай, msg
переместить_имм рдикс, 13
вызов_системы
## 2. Синтаксис языка КВС ; exit(0)
переместить_имм раикс, 60
переместить_имм рдиай, 0
вызов_системы
### 2.1. Структура программы .данные
msg: .строка_нуль "Hello, World!"
```
Программа на КВС состоит из секций: ### 2. Скомпилируйте:
```bash
python3 kvs_build.py hello.квс
```
### 3. Запустите:
```bash
./hello.elf
```
**Вывод:**
```
Hello, World!
```
## 📝 Синтаксис
### Структура программы
``` ```
.текст ; секция кода (обязательна) .текст ; секция кода (обязательна)
@ -56,60 +137,28 @@ python3 kvs_build.py <файл.квс>
; ... данные ... ; ... данные ...
``` ```
### 2.2. Метки ### Метки
Метка — это имя, за которым следует двоеточие. Метки могут использоваться как цели переходов. Метка — это имя, за которым следует двоеточие:
``` ```asm
_start: ; метка _start _start: ; метка _start
переместить_имм раикс, 1 переместить_имм раикс, 1
переход _start ; переход на метку переход _start ; переход на метку
``` ```
### 2.3. Директивы ### Комментарии
| Директива | Назначение | Пример |
|-----------|------------|--------|
| `.текст` | Начало секции кода | `.текст` |
| `.данные` | Начало секции данных | `.данные` |
| `.глобал` | Объявление глобальной метки (точки входа) | `.глобал _start` |
| `.строка` | Строка без завершающего нуля | `.строка "Hello"` |
| `.строка_нуль` | Строка с завершающим нулём | `.строка_нуль "Hello"` |
| `.байт` | Последовательность байтов | `.байт 0x48, 0x65, 108` |
| `.константа` | Определение константы | `.константа LEN = 10` |
### 2.4. Комментарии
Однострочные комментарии начинаются с `;`: Однострочные комментарии начинаются с `;`:
``` ```asm
; Это комментарий ; Это комментарий
переместить_имм раикс, 42 ; комментарий после инструкции переместить_имм раикс, 42 ; комментарий после инструкции
``` ```
--- ## 📖 Система команд
## 3. Система команд ### Загрузка констант
### 3.1. Регистры
КВС поддерживает все основные 64-битные регистры x86-64 в различных размерностях:
| Размер | 64-бит | 32-бит | 16-бит | 8-бит (мл.) | 8-бит (ст.) |
|--------|--------|--------|--------|-------------|-------------|
| RAX | `раикс` | `еаикс` | `аикс` | `ал` | `аш` |
| RCX | `рсикс` | `есикс` | `сикс` | `кл` | `чш` |
| RDX | `рдикс` | `едикс` | `дикс` | `дл` | `дш` |
| RBX | `рбикс` | `ебикс` | `бикс` | `бл` | `бш` |
| RSP | `рсипи` | `есипи` | `эсп` | `спл` | — |
| RBP | `рбипи` | `ебипи` | `бипи` | `бпл` | — |
| RSI | `рсиай` | `есиай` | `эс` | `сил` | — |
| RDI | `рдиай` | `едиай` | `ди` | `дил` | — |
| R8-R15 | `р8`…`р15` | `р8д`…`р15д` | `р8в`…`р15в` | `р8б`…`р15б` | — |
### 3.2. Инструкции
#### Загрузка констант
| Инструкция | Синтаксис | Описание | | Инструкция | Синтаксис | Описание |
|------------|-----------|----------| |------------|-----------|----------|
@ -117,11 +166,11 @@ _start: ; метка _start
```asm ```asm
переместить_имм раикс, 42 ; RAX = 42 переместить_имм раикс, 42 ; RAX = 42
переместить_имм еаикс, 0x7FFF ; EAX = 32767 (32-бит) переместить_имм еаикс, 0x7FFF ; EAX = 32767
переместить_имм ал, 0xFF ; AL = 255 (8-бит) переместить_имм ал, 0xFF ; AL = 255
``` ```
#### Арифметика и логика ### Арифметика и логика
| Инструкция | Синтаксис | Описание | | Инструкция | Синтаксис | Описание |
|------------|-----------|----------| |------------|-----------|----------|
@ -129,9 +178,9 @@ _start: ; метка _start
| `вычесть` | `вычесть рег1, рег2` | рег1 -= рег2 | | `вычесть` | `вычесть рег1, рег2` | рег1 -= рег2 |
| `увеличить` | `увеличить рег` | рег++ | | `увеличить` | `увеличить рег` | рег++ |
| `уменьшить` | `уменьшить рег` | рег-- | | `уменьшить` | `уменьшить рег` | рег-- |
| `сравнить` | `сравнить рег1, рег2` | Сравнить два регистра (установка флагов) | | `сравнить` | `сравнить рег1, рег2` | Сравнить регистры |
| `сравнить_с` | `сравнить_с рег, значение` | Сравнить регистр с константой | | `сравнить_с` | `сравнить_с рег, значение` | Сравнить с константой |
| `проверить` | `проверить рег1, рег2` | TEST — логическое AND (установка ZF) | | `проверить` | `проверить рег1, рег2` | TEST (логическое AND) |
```asm ```asm
прибавить раикс, рбикс ; RAX += RBX прибавить раикс, рбикс ; RAX += RBX
@ -139,80 +188,69 @@ _start: ; метка _start
сравнить раикс, 10 ; сравнить RAX с 10 сравнить раикс, 10 ; сравнить RAX с 10
``` ```
#### Переходы ### Переходы
| Инструкция | Синтаксис | Условие | | Инструкция | Условие |
|------------|-----------|---------| |------------|---------|
| `переход` | `переход метка` | Безусловный | | `переход` | Безусловный |
| `короткий_переход` | `короткий_переход метка` | Безусловный (смещение ±127) | | `короткий_переход` | Безусловный (смещение ±127) |
| `переход_если_равно` | `переход_если_равно метка` | ZF = 1 | | `переход_если_равно` | ZF = 1 |
| `переход_если_неравно` | `переход_если_неравно метка` | ZF = 0 | | `переход_если_неравно` | ZF = 0 |
| `переход_если_меньше` | `переход_если_меньше метка` | SF ≠ OF (signed <) | | `переход_если_меньше` | SF ≠ OF (signed <) |
| `переход_если_больше` | `переход_если_больше метка` | ZF = 0 и SF = OF (signed >) | | `переход_если_больше` | ZF = 0 и SF = OF (signed >) |
| `переход_если_меньше_или_равно` | `переход_если_меньше_или_равно метка` | ZF = 1 или SF ≠ OF | | `переход_если_меньше_или_равно` | ZF = 1 или SF ≠ OF |
| `переход_если_больше_или_равно` | `переход_если_больше_или_равно метка` | SF = OF | | `переход_если_больше_или_равно` | SF = OF |
| `переход_если_перенос` | `переход_если_перенос метка` | CF = 1 | | `переход_если_перенос` | CF = 1 |
| `переход_если_нет_переноса` | `переход_если_нет_переноса метка` | CF = 0 | | `переход_если_нет_переноса` | CF = 0 |
| `переход_если_ноль` | `переход_если_ноль метка` | ZF = 1 (синоним JE) |
| `переход_если_не_ноль` | `переход_если_не_ноль метка` | ZF = 0 (синоним JNE) |
**Короткие условные переходы** (префикс `короткий_`): **Короткие условные переходы** (префикс `короткий_`):
- `короткий_переход_если_равно`, `короткий_переход_если_неравно`, и т.д. - `короткий_переход_если_равно`, `короткий_переход_если_неравно`, и т.д.
- Генерируют 2-байтовые инструкции (смещение ±127 байт) - Генерируют 2-байтовые инструкции (смещение ±127 байт)
#### Системные вызовы ### Системные вызовы
| Инструкция | Синтаксис | Описание | | Инструкция | Описание |
|------------|-----------|----------| |------------|----------|
| `вызов_системы` | `вызов_системы` | Вызов ядра Linux (syscall) | | `вызов_системы` | Вызов ядра Linux (syscall) |
```asm ```asm
; Пример: вывод строки
переместить_имм раикс, 1 ; syscall 1 = write
переместить_имм рдиай, 1 ; stdout
переместить_имм рсиай, msg ; указатель на строку
переместить_имм рдикс, len ; длина строки
вызов_системы
; Пример: завершение программы ; Пример: завершение программы
переместить_имм раикс, 60 ; syscall 60 = exit переместить_имм раикс, 60 ; syscall 60 = exit
переместить_имм рдиай, 0 ; код возврата 0 переместить_имм рдиай, 0 ; код возврата 0
вызов_системы вызов_системы
``` ```
#### Прочие инструкции ## 💾 Регистры процессора
| Инструкция | Синтаксис | Описание | КВС поддерживает все основные 64-битные регистры x86-64:
|------------|-----------|----------|
| `нет_операции` | `нет_операции` | NOP (0x90) |
--- | 64-бит | 32-бит | 16-бит | 8-бит (мл.) | 8-бит (ст.) |
|--------|--------|--------|-------------|-------------|
| `раикс` | `еаикс` | `аикс` | `ал` | `аш` |
| `рбикс` | `ебикс` | `бикс` | `бл` | `бш` |
| `рсикс` | `есикс` | `сикс` | `кл` | `чш` |
| `рдикс` | `едикс` | `дикс` | `дл` | `дш` |
| `рсипи` | `есипи` | `эсп` | `спл` | — |
| `рбипи` | `ебипи` | `бипи` | `бпл` | — |
| `рсиай` | `есиай` | `эс` | `сил` | — |
| `рдиай` | `едиай` | `ди` | `дил` | — |
| `р8`…`р15` | `р8д`…`р15д` | `р8в`…`р15в` | `р8б`…`р15б` | — |
## 4. Примеры программ ## 🔧 Директивы ассемблера
### 4.1. Hello World | Директива | Назначение | Пример |
|-----------|------------|--------|
| `.текст` | Начало секции кода | `.текст` |
| `.данные` | Начало секции данных | `.данные` |
| `.глобал` | Объявление глобальной метки | `.глобал _start` |
| `.строка` | Строка без завершающего нуля | `.строка "Hello"` |
| `.строка_нуль` | Строка с завершающим нулём | `.строка_нуль "Hello"` |
| `.байт` | Последовательность байтов | `.байт 0x48, 0x65, 108` |
| `.константа` | Определение константы | `.константа LEN = 10` |
```asm ## 📝 Примеры программ
.текст
.глобал _start
_start: ### Цикл и условный переход
переместить_имм раикс, 1
переместить_имм рдиай, 1
переместить_имм рсиай, msg
переместить_имм рдикс, len_msg
вызов_системы
переместить_имм раикс, 60
переместить_имм рдиай, 0
вызов_системы
.данные
msg: .строка_нуль "Hello, World!\n"
.константа len_msg = 15
```
### 4.2. Цикл и условный переход
```asm ```asm
.текст .текст
@ -222,7 +260,6 @@ _start:
переместить_имм рсикс, 10 ; счетчик = 10 переместить_имм рсикс, 10 ; счетчик = 10
loop: loop:
; тело цикла
переместить_имм раикс, 1 переместить_имм раикс, 1
переместить_имм рдиай, 1 переместить_имм рдиай, 1
переместить_имм рсиай, msg переместить_имм рсиай, msg
@ -242,112 +279,70 @@ loop:
.константа len_msg = 10 .константа len_msg = 10
``` ```
--- ### Вычисление суммы чисел от 1 до 10
## 5. Проверка исполняемого файла стандартными утилитами ```asm
.текст
.глобал _start
### 5.1. Запуск программы _start:
переместить_имм р8, 0 ; сумма
```bash переместить_имм р9, 10 ; счётчик
./<имя>.elf
``` loop:
прибавить р8, р9
### 5.2. Просмотр секций (`objdump -h`) уменьшить р9
сравнить_с р9, 0
```bash переход_если_больше loop
objdump -h программа.elf
``` ; exit(сумма в r8)
переместить_имм раикс, 60
Вывод показывает размер, виртуальный адрес и атрибуты каждой секции. переместить рдикс, р8
вызов_системы
``` ```
Разделы:
Idx Name Разм VMA LMA Фа смещ. ## 🐛 Отладка и проверка
0 .text 00000232 0000000000401000 0000000000401000 00001000
1 .data 0000011c 0000000000402000 0000000000402000 00002000 ### Просмотр сгенерированного кода
```
### 5.3. Дизассемблирование (`objdump -d`)
```bash ```bash
# Дизассемблирование
objdump -d программа.elf objdump -d программа.elf
```
Показывает машинный код в виде ассемблерных инструкций x86-64. # Просмотр секций
objdump -h программа.elf
```bash # Просмотр заголовков программы
# Ограничить вывод
objdump -d программа.elf | head -50
# Сохранить в файл
objdump -d программа.elf > код.asm
```
### 5.4. Просмотр заголовков программы (`readelf -l`)
```bash
readelf -l программа.elf readelf -l программа.elf
```
Показывает сегменты LOAD, их смещения, виртуальные адреса и права доступа. # Извлечение строк из ELF
```
Заголовки программы:
Тип Смещ. Вирт.адр Физ.адр Рзм.фйл Рзм.пм Флаги
LOAD 0x001000 0x401000 0x401000 0x232 0x1000 R E
LOAD 0x002000 0x402000 0x402000 0x11c 0x1000 RW
```
### 5.5. Проверка целостности ELF (`readelf -h`)
```bash
readelf -h программа.elf
```
Выводит заголовок ELF-файла (магия, тип, архитектура, точка входа).
### 5.6. Просмотр всех заголовков секций (`readelf -S`)
```bash
readelf -S программа.elf
```
### 5.7. Сравнение двух ELF-файлов
```bash
# Сравнить дизассемблированный код
diff <(objdump -d файл1.elf) <(objdump -d файл2.elf)
# Сравнить заголовки секций
diff <(objdump -h файл1.elf) <(objdump -h файл2.elf)
```
### 5.8. Просмотр строк из секции `.data`
```bash
# Извлечь строки из ELF
strings программа.elf strings программа.elf
# Показать шестнадцатеричный дамп секции .data
objdump -s -j .data программа.elf
``` ```
### 5.9. Трассировка системных вызовов ### CSV-лог
После компиляции создаётся файл `программа.csv` со структурой:
| адрес | байт | целевой_адрес | исходная_команда |
|-------|------|---------------|------------------|
| 0x401000 | 48 | | переместить_имм раикс, 1 |
| 0x401001 | B8 | | |
| 0x401002 | 01 | | |
| ... | ... | ... | ... |
### Трассировка системных вызовов
```bash ```bash
strace ./программа.elf strace ./программа.elf
``` ```
Показывает все системные вызовы, выполняемые программой. ### Отладка с GDB
### 5.10. Отладка с GDB
```bash ```bash
gdb ./программа.elf gdb ./программа.elf
``` ```
В GDB: ```gdb
```
(gdb) break _start ; установить точку останова (gdb) break _start ; установить точку останова
(gdb) run ; запустить (gdb) run ; запустить
(gdb) info registers ; показать регистры (gdb) info registers ; показать регистры
@ -355,11 +350,9 @@ gdb ./программа.elf
(gdb) stepi ; выполнить одну инструкцию (gdb) stepi ; выполнить одну инструкцию
``` ```
--- ## ⚠️ Ограничения
## 6. Особенности и ограничения ### Поддерживается
### 6.1. Поддерживаемые возможности
- ✅ 64-битные, 32-битные, 16-битные и 8-битные регистры - ✅ 64-битные, 32-битные, 16-битные и 8-битные регистры
- ✅ Непосредственная загрузка констант (imm) в регистры - ✅ Непосредственная загрузка констант (imm) в регистры
@ -368,51 +361,26 @@ gdb ./программа.elf
- ✅ Арифметические операции (ADD, SUB, INC, DEC) - ✅ Арифметические операции (ADD, SUB, INC, DEC)
- ✅ Логическая операция TEST - ✅ Логическая операция TEST
- ✅ Системные вызовы Linux (syscall) - ✅ Системные вызовы Linux (syscall)
- ✅ Секции `.text` и `.data` - ✅ Секции `.текст` и `.данные`
- ✅ Строковые литералы с escape-последовательностями (`\n`, `\t`, `\\`, `\"`) - ✅ Строковые литералы с escape-последовательностями (`\n`, `\t`, `\\`, `\"`)
- ✅ Директива `.байт` для raw-данных - ✅ Директива `.байт` для raw-данных
- ✅ Директива `.константа` для имён констант - ✅ Директива `.константа` для имён констант
### 6.2. Ограничения ### Не поддерживается
- ❌ Отсутствует поддержка косвенной адресации памяти `[reg+disp]` - ❌ Косвенная адресация памяти `[reg+disp]` (в разработке)
- ❌ Нет инструкций для работы со стеком (PUSH, POP, CALL, RET) - ❌ Инструкции для работы со стеком (PUSH, POP, CALL, RET)
- ❌ Нет поддержки плавающей запятой (FPU/SSE) - ❌ Поддержка плавающей запятой (FPU/SSE)
- ❌ Нет многомодульной компиляции - ❌ Многомодульная компиляция
- ❌ Нет макросов - ❌ Макросы
### 6.3. Примечания ## 📄 Лицензия
- Все переходы используют абсолютные целевые адреса (метки преобразуются в адреса) Только для образовательных целей. Используйте на свой страх и риск.
- Для длинных переходов генерируется 5-байтовая инструкция JMP или 6-байтовая Jcc
- Секция `.data` выравнивается на границу страницы (0x1000) после `.text`
- Точка входа по умолчанию — `_start`
---
## 7. Сообщения об ошибках
Компилятор выводит подробные сообщения об ошибках с указанием файла и строки:
``` ```
Ошибка в файле test.квс, строка 42: КВС Ассемблер | Экспериментальный проект | 2025
переместить_имм аикс, 100000 Только для образовательных целей. Используйте на свой страх и риск.
Неподдерживаемый размер регистра
``` ```
Основные ошибки: ```
| Сообщение | Причина |
|-----------|---------|
| `Неизвестная инструкция: '...'` | Неверное имя инструкции |
| `Недопустимый формат числа: '...'` | Неверный синтаксис числа |
| `Недопустимый регистр` | Регистр не найден в таблице |
| `Метка не найдена: '...'` | Использование неопределённой метки |
| `Цель слишком далеко для короткого перехода` | Смещение > 127 байт для условного перехода |
| `Незакрытая кавычка в строке` | Ошибка в синтаксисе строки |
---
## 8. Заключение
Компилятор КВС предоставляет возможность писать низкоуровневые программы на русскоязычном ассемблероподобном языке с последующей компиляцией в нативный 64-битный ELF-исполняемый файл. Декомпозированная архитектура компилятора облегчает понимание этапов трансляции и модификацию отдельных модулей.