kmp/README.md

```markdown
# ndisasm-ru — Русский дизассемблер x86-64 для языка КВС

**ndisasm-ru** — это модифицированная версия утилиты `ndisasm` из пакета **Netwide Assembler (NASM)**, адаптированная для вывода дизассемблированного кода на русском языке в синтаксисе языка **КВС**.

---

## 📌 Особенности

- ✅ **Перевод мнемоник** инструкций x86-64 на русский язык
- ✅ **Перевод регистров** (64, 32, 16, 8-битных) на русский язык
- ✅ **Числовые значения** остаются без изменений
- ✅ **Синтаксис** соответствует языку программирования КВС
- ✅ **Полная совместимость** с оригинальным `ndisasm` по функциональности
- ✅ **Независимая сборка** — не требует наличия NASM

---

## 🚀 Быстрый старт

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

# Сборка
make

# Запуск
./ndisasm-ru -b 64 файл.elf
```

---

## 📖 Пример вывода

Ниже приведён фрагмент дизассемблирования самого `ndisasm-ru` в 64-битном режиме. Хорошо видно, как инструкции и регистры переводятся на русский язык:

```bash
$ ./ndisasm-ru -b 64 -o 0x81380 -e 0x81380 ndisasm-ru | head -20
00081380  B957040000        переместить есикс,0x457
00081385  488D154C6A0000    загрузить_адрес рдикс,[rel 0x87dd8]
0008138C  488D355D6F0000    загрузить_адрес рсиай,[rel 0x882f0]
00081393  488D3D4B6A0000    загрузить_адрес рдиай,[rel 0x87de5]
0008139A  E87F010000        вызвать 0x8151e
0008139F  F30F1EFA          endbr64
000813A3  50                втолкнуть раикс
000813A4  58                вытолкнуть раикс
000813A5  50                втолкнуть раикс
000813A6  E8B5540000        вызвать 0x86860
000813AB  E860FEFFFF        вызвать 0x81210
000813B0  F30F1EFA          endbr64
000813B4  50                втолкнуть раикс
000813B5  58                вытолкнуть раикс
000813B6  488D3DC3720000    загрузить_адрес рдиай,[rel 0x88680]
000813BD  50                втолкнуть раикс
000813BE  31C0              исключающее_или еаикс,еаикс
000813C0  E805000000        вызвать 0x813ca
000813C5  E8E6FFFFFF        вызвать 0x813b0
000813CA  F30F1EFA          endbr64
```

**Что мы видим в этом выводе:**
- `mov ecx,0x457` → `переместить есикс,0x457`
- `lea rdx,[rel 0x87dd8]` → `загрузить_адрес рдикс,[rel 0x87dd8]`
- `call 0x8151e` → `вызвать 0x8151e`
- `push rax` → `втолкнуть раикс`
- `pop rax` → `вытолкнуть раикс`
- `xor eax,eax` → `исключающее_или еаикс,еаикс`

---

## 📂 Структура проекта

```
ndisasm-ru/
├── src/
│   ├── ndisasm.c          # Основной файл дизассемблера (с патчем)
│   ├── zamenyator.c       # Модуль перевода мнемоник и регистров
│   ├── zamenyator.h       # Заголовок модуля перевода
│   ├── disasm.c           # Ядро дизассемблера (оригинал)
│   ├── sync.c             # Синхронизация (оригинал)
│   └── ...                # Остальные файлы из NASM
├── include/               # Заголовочные файлы
├── Makefile               # Makefile для сборки
└── README.md              # Этот файл
```

---

## 📋 Таблица перевода

### Мнемоники (основные)

| Английская | Русская (КВС) |
|---|---|
| `mov` | `переместить` |
| `add` | `прибавить` |
| `sub` | `вычесть` |
| `cmp` | `сравнить` |
| `jmp` | `переход` |
| `je` / `jz` | `переход_если_равно` / `переход_если_ноль` |
| `jne` / `jnz` | `переход_если_неравно` / `переход_если_не_ноль` |
| `call` | `вызвать` |
| `ret` | `вернуться` |
| `push` | `втолкнуть` |
| `pop` | `вытолкнуть` |
| `test` | `проверить` |
| `xor` | `исключающее_или` |
| `and` | `и` |
| `or` | `или` |
| `inc` | `увеличить` |
| `dec` | `уменьшить` |
| `syscall` | `вызов_системы` |
| `nop` | `нет_операции` |
| `lea` | `загрузить_адрес` |

Полный список мнемоник и регистров см. в файле `src/zamenyator.c`.

### Регистры

| Английский | Русский (КВС) |
|---|---|
| `rax` | `раикс` |
| `rbx` | `рбикс` |
| `rcx` | `рсикс` |
| `rdx` | `рдикс` |
| `rsi` | `рсиай` |
| `rdi` | `рдиай` |
| `rsp` | `рсипи` |
| `rbp` | `рбипи` |
| `r8` – `r15` | `р8` – `р15` |
| `eax` | `еаикс` |
| `ebx` | `ебикс` |
| `ecx` | `есикс` |
| `edx` | `едикс` |
| `esi` | `есиай` |
| `edi` | `едиай` |
| `esp` | `есипи` |
| `ebp` | `ебипи` |

---

## 🔧 Использование

### Основные опции

```bash
./ndisasm-ru -b 16/32/64 файл   # Установка разрядности
./ndisasm-ru -o смещение файл   # Установка базового адреса
./ndisasm-ru -e байты файл      # Пропуск заголовка
./ndisasm-ru -k старт,байты     # Пропуск региона
./ndisasm-ru -h                  # Справка
```

### Примеры

```bash
# Дизассемблирование 32-битного бинарного файла
./ndisasm-ru -b 32 program.bin

# Дизассемблирование 64-битного ELF-файла с пропуском заголовка
./ndisasm-ru -b 64 -e 0x40 program.elf

# Дизассемблирование с указанием виртуального адреса
./ndisasm-ru -b 64 -o 0x400000 -e 0x81380 program.elf
```

---

## 🧪 Тестирование

```bash
# Сборка и тестирование
make test
```

Или вручную:

```bash
# Создание тестового файла
echo -n -e "\xB8\x01\x00\x00\x00" > test.bin

# Запуск теста
./ndisasm-ru -b 32 test.bin

# Ожидаемый вывод: 00000000  B801000000        переместить еаикс,0x1
```

---

## ⚠️ Ограничения

- Поддерживаются только инструкции x86-64, присутствующие в таблице перевода
- Некоторые специфические инструкции (SSE, AVX, CET) могут отображаться на английском
- Сегментные префиксы пока не переведены

---

## 📜 Лицензия и авторство

### Оригинальный проект NASM

Исходный код основан на проекте **Netwide Assembler (NASM)**.

- **Автор:** Simon Tatham, Julian Hall и другие участники проекта NASM
- **Официальный сайт:** https://www.nasm.us/
- **Исходный код:** https://git.nasm.us/nasm.git
- **Лицензия:** BSD 2-Clause License

> Авторские права © 1996-2025 Авторы NASM. Все права защищены.
>
> Распространение и использование разрешены при условии сохранения
> уведомления об авторских правах и списка условий.
> Подробнее: https://opensource.org/licenses/BSD-2-Clause

### Модификация для КВС

- **Автор модификации:** artradeskz
- **Проект:** https://github.com/artradeskz/ndisasm-ru
- **Назначение:** Адаптация для языка программирования КВС

Модификация включает:
- Добавление модуля `zamenyator` для перевода мнемоник и регистров
- Патч `ndisasm.c` для вызова переводчика в функции `output_ins()`
- Сборка в независимый проект

---

## 🤝 Благодарности

- Команде разработчиков **NASM** за отличный инструмент
- Сообществу **КВС** за вдохновение

---

## 🔗 Ссылки

- [Проект КВС](https://github.com/artradeskz/kvs)
- [Официальный сайт NASM](https://www.nasm.us/)
- [Исходный код NASM](https://git.nasm.us/nasm.git)

---

## 📧 Контакты

По вопросам и предложениям: [GitHub Issues](https://github.com/artradeskz/ndisasm-ru/issues)

---

*ndisasm-ru — Русский дизассемблер для КВС*
```