Create readme.md

2025-12-23 16:07:23 +03:00 · 2025-12-23 16:07:23 +03:00 · b010a9a5b9
parent bc2929a47a
commit b010a9a5b9
1 changed files with 154 additions and 0 deletions
--- a/readme.md
+++ 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 могут быть заполнены упрощённо.
+