diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..248d053 --- /dev/null +++ b/readme.md @@ -0,0 +1,154 @@ +# КВС (kvs_9_8.py) — Ассемблер с русским синтаксисом для x86-64 + +## 📖 Оглавление +- [🎯 Назначение и концепция](#-назначение-и-концепция) +- [🚀 Особенности и возможности](#-особенности-и-возможности) +- [⚙️ Архитектура и процесс сборки](#️-архитектура-и-процесс-сборки) +- [📁 Формат исходных файлов (.квс)](#-формат-исходных-файлов-квс) +- [🔧 Система команд (инструкции)](#-система-команд-инструкции) +- [💾 Регистры процессора](#-регистры-процессора) +- [📋 Директивы ассемблера](#-директивы-ассемблера) +- [📦 Система импорта модулей](#-система-импорта-модулей) +- [🔄 Процесс трансляции и выходные файлы](#-процесс-трансляции-и-выходные-файлы) +- [⚠️ Ограничения и особенности реализации](#️-ограничения-и-особенности-реализации) + +## 🎯 Назначение и концепция + +**КВС** — это ассемблер для архитектуры x86-64, полностью использующий **русскую лексику** для мнемоник инструкций, имён регистров и директив. Проект носит **образовательный и экспериментальный характер** и демонстрирует принципы работы ассемблера, построения ELF-файлов и трансляции высокоуровневых концепций в машинный код. + +**Ключевые философские принципы проекта:** +* **Самодокументируемый код**: Читаемость и ясность важнее краткости. +* **Изоляция логики**: Разделение парсера, трансформатора и кодогенератора. +* **Минимизация зависимостей**: Используется только `struct` для упаковки данных, `re` не используется. +* **Избегание чрезмерного ООП**: В контексте возможной будущей самокомпиляции. + +## 🚀 Особенности и возможности + +* **Полностью русский синтаксис**: Все инструкции (`переместить`, `прибавить`, `вызвать`), регистры (`раикс`, `есипи`, `ал`) и директивы (`.текст`, `.данные`) используют кириллицу. +* **Генерация исполняемых ELF-файлов**: На выходе создаются 64-битные ELF-файлы для Linux, готовые к запуску. +* **Двухпроходная сборка**: Традиционная для ассемблеров схема с разрешением меток. +* **Поддержка секций**: Явное разделение на секции кода (`.текст`) и данных (`.данные`). +* **Система импорта модулей**: Директива `.импорт` для включения других файлов `.квс` с автоматическим разрешением имён. +* **Подготовка к сложной адресации**: Архитектура заложена для будущей трансформации сложных режимов адресации памяти в последовательности простых инструкций через промежуточное представление. +* **Детальное логирование**: Генерация `.log.csv` файла с полным соответствием машинных кодов, виртуальных адресов и исходных команд. + +## ⚙️ Архитектура и процесс сборки + +Процесс трансляции исходного кода `.квс` в исполняемый файл `.elf` проходит через несколько этапов: + +``` +Исходный файл (.квс) + │ + ▼ (Этап 1: Разбор и импорт) +Промежуточный файл (.квс.промежуточный) + │ + ▼ (Этап 2: Двухпроходное ассемблирование) +Данные секций + Таблица меток + │ + ▼ (Этап 3: Генерация ELF) +Исполняемый файл (.elf) + Лог (.log.csv) +``` + +**Подробнее об этапах:** +1. **Построение промежуточного представления**: Исходный файл и все импортированные модули объединяются в один текст. Метки и константы переименовываются (получают суффикс имени модуля) для избежания коллизий. +2. **Первый проход ассемблирования**: Анализируется промежуточный файл, вычисляются размеры всех инструкций и данных, строится таблица меток с их смещениями внутри секций. +3. **Второй проход ассемблирования**: Генерируется машинный код. Адреса меток подставляются в инструкции переходов, загрузки адресов и т.д. Формируются бинарные содержимое секций `.text` и `.data`. +4. **Компоновка ELF**: Собранные секции упаковываются в формат исполняемого файла ELF 64-bit с корректными заголовками, таблицами секций и сегментов. + +## 📁 Формат исходных файлов (.квс) + +Исходные файлы имеют расширение `.квс`. Их структура следует традициям ассемблера: + +```asm +; Комментарий начинается с точки с запятой +.данные ; Начало секции данных + приветствие: .строка_нуль "Здравствуй, мир!" + число: .байт 0x2A + +.текст ; Начало секции кода +.глобал _start ; Объявление точки входа + +_start: ; Метка + переместить_имм раикс, 60 ; Системный вызов exit (60) в rax + переместить_имм рдикс, 42 ; Код возврата (42) в rdi + вызов_системы ; Вызов ядра (syscall) +``` + +## 🔧 Система команд (инструкции) + +Ассемблер поддерживает обширный набор инструкций x86-64, сгруппированных по категориям: + +| Категория | Примеры инструкций | Соответствие NASM | +| :--- | :--- | :--- | +| **Перемещение данных** | `переместить`, `загрузить`, `сохранить`, `загрузить_адрес` | `mov`, `lea` | +| **Арифметика** | `прибавить`, `вычесть`, `умножить`, `разделить`, `увеличить` | `add`, `sub`, `mul`, `div`, `inc` | +| **Логические операции** | `и`, `или`, `инвертировать`, `проверить` | `and`, `or`, `not`, `test` | +| **Управление потоком** | `переход`, `переход_если_равно`, `вызвать`, `вернуться` | `jmp`, `je`, `call`, `ret` | +| **Работа со стеком** | `втолкнуть`, `вытолкнуть` | `push`, `pop` | +| **Сдвиги и вращения** | `сдвиг_влево`, `вращать_вправо` | `shl`, `ror` | +| **Строковые операции** | `переместить_байт`, `сравнить_байты` | `movsb`, `cmpsb` | +| **Системные вызовы** | `вызов_системы`, `прервать` | `syscall`, `int` | + +**Особенности кодирования:** Проект корректно генерирует префиксы REX, учитывает размеры операндов (8/16/32/64 бита) и поддерживает базовые режимы адресации памяти (например, `[раикс]`). + +## 💾 Регистры процессора + +Поддерживаются регистры x86-64 во всех их размерах: + +| 64-битные | 32-битные | 16-битные | 8-битные (младшие) | 8-битные (старшие) | +| :--- | :--- | :--- | :--- | :--- | +| `раикс` | `еаикс` | `аикс` | `ал` | `аш` | +| `рбикс` | `ебикс` | `бикс` | `бл` | `бш` | +| `рсикс` | `есикс` | `сикс` | `кл` | `чш` | +| `рдикс` | `едикс` | `дикс` | `дл` | `дш` | +| `рсипи` | `есипи` | `эсп` | `спл` | — | +| `рбипи` | `ебипи` | `бипи` | `бпл` | — | +| `рсиай` | `есиай` | `эс` | `сил` | — | +| `рдиай` | `едиай` | `ди` | `дил` | — | +| `р8` ... `р15` | `р8д` ... `р15д` | `р8в` ... `р15в` | `р8б` ... `р15б` | — | + +## 📋 Директивы ассемблера + +Директивы управляют процессом ассемблирования, не превращаясь в машинный код напрямую. + +| Директива | Описание | Пример | +| :--- | :--- | :--- | +| `.текст` | Переключает ассемблер на запись в секцию кода. | `.текст` | +| `.данные` | Переключает ассемблер на запись в секцию данных. | `.данные` | +| `.глобал` | Объявляет метку глобальной (точку входа программы). | `.глобал _start` | +| `.строка` / `.строка_нуль` | Резервирует место в секции данных для строки (без нуля / с нулевым завершителем). | `.строка_нуль "Текст"` | +| `.байт` | Резервирует один или несколько байт с заданными значениями. | `.байт 1, 0xFE, 255` | +| `.константа` | Определяет символьную константу, которую можно использовать как число. | `.константа ВЫХОД = 60` | +| `.импорт` | Включает содержимое другого файла `.квс` в текущую сборку. | `.импорт библиотека.квс` | + +## 📦 Система импорта модулей + +Директива `.импорт` позволяет разбивать проект на несколько файлов. + +**Принцип работы:** +1. **Рекурсивный поиск**: Ассемблер ищет указанный файл в той же директории, что и импортирующий файл. +2. **Переименование**: Чтобы избежать конфликтов имён, все метки и константы импортированного модуля автоматически получают суффикс, основанный на имени файла (например, метка `цикл` из `модуль.квс` станет `цикл_модуль`). +3. **Объединение**: Содержимое всех секций `.данные` из импортированных файлов сливается в общую секцию `.данные` промежуточного файла. Аналогично для `.текст`. + +Это упрощает создание библиотек и организацию больших проектов. + +## 🔄 Процесс трансляции и выходные файлы + +Запуск ассемблера: +```bash +python3 kvs_9_8.py программа.квс +``` + +**В результате создаются три файла:** +1. **`программа.квс.промежуточный`**: Текстовый файл, содержащий объединённый и переименованный код всех модулей. Используется для отладки процесса импорта. +2. **`программа.elf`**: Исполняемый 64-битный ELF-файл. Для запуска может потребоваться установить флаг исполнения: `chmod +x программа.elf`. +3. **`программа.log.csv`**: Детальный лог в формате CSV, где для каждого байта машинного кода указан его виртуальный адрес, шестнадцатеричное значение, целевой адрес (для инструкций переходов) и исходная команда на русском языке. Неоценим для обучения и отладки. + +## ⚠️ Ограничения и особенности реализации + +* **Экспериментальный статус**: Проект в активной разработке, некоторые углы архитектуры x86-64 могут быть реализованы не полностью. +* **Базовая адресация памяти**: На данный момент поддерживаются преимущественно простые формы адресации (например, `[регистр]`). Режимы со сдвигом и несколькими регистрами (`[база + индекс*масштаб + смещение]`) предназначены для реализации через **трансформацию в промежуточном представлении** (задел на будущее). +* **Отсутствие макросов и условной компиляции**: В текущей версии эти конструкции не поддерживаются. +* **Лексический анализатор (лексер)**: Написан "вручную", без использования регулярных выражений (`re`), в соответствии с философией проекта. +* **Генерация ELF**: Реализация фокусируется на создании рабочих исполняемых файлов для Linux. Некоторые необязательные или специфичные поля заголовков ELF могут быть заполнены упрощённо. +