docs: update readme and add docs

Author: alexeev-prog

CHANGELOG.md

@@ -1,3 +1,9 @@
+commit fc36ce4c4630d7468c9cc562f977fbc3bcf51146
+Author: Alexeev Bronislav <alexeev.dev@mail.ru>
+Date:   Sat Aug 23 04:14:24 2025 +0700
+
+    fix shell prompt bug, fix kernel
+
 commit 34f4acc8359288ab92953aaaaa2d1dc4ccf9de50
 Author: Alexeev Bronislav <alexeev.dev@mail.ru>
 Date:   Sat Aug 23 03:21:09 2025 +0700

README.md

@@ -1,5 +1,6 @@
 # KintsugiOS
-Минималистичная x86 операционная система на (N)ASM и С.
+
+Минималистичная x86 операционная система на (N)ASM и C, созданная в образовательных целях для глубокого понимания принципов работы операционных систем.
 
 <div align="center">
 <img src=https://img.shields.io/github/languages/top/alexeev-prog/KintsugiOS>
@@ -8,96 +9,184 @@
 <img src="https://img.shields.io/github/issues/alexeev-prog/KintsugiOS">
 </div>
 
-## Requirements
-Этот проект использует [кросс компилятор i386 ELF GCC](http://newos.org/toolchains/i386-elf-15.1.0-Linux-x86_64.tar.xz), FASM 1.73, NASM 2.16 и GDB, MTools, Xorriso.
+![KintsugiOS Screenshot](https://via.placeholder.com/800x400/000000/FFFFFF/?text=KintsugiOS+Screenshot)
+
+## Особенности
+
+### Реализовано
+- **Загрузчик** с переходом из реального режима в защищённый
+- **GDT** (Глобальная таблица дескрипторов)
+- **Управление памятью** с двумя аллокаторами:
+  - Арена-аллокатор (legacy)
+  - Аллокатор на основе связанных блоков памяти
+- **Драйверы**:
+  - VGA-экран с поддержкой цветного текста
+  - Клавиатура (PS/2)
+  - Таймер
+- **Система прерываний** (IDT, ISR, IRQ)
+- **Командная оболочка** "Keramika Shell" с поддержкой команд:
+  - `HELP` - список команд
+  - `CLEAR` - очистка экрана
+  - `END` - остановка CPU
+  - `AMALLOC`/`MALLOC` - выделение памяти
+  - `FREE` - освобождение памяти
+  - `INFO` - информация о системе
+  - `MEMDUMP` - дамп памяти
+  - И другие...
+- **Библиотека LibC** включая:
+  - Работу со строками (string.h)
+  - Форматированный вывод (stdio.h)
+  - Функции памяти (mem.h)
+
+### В разработке
+- [ ] Виртуальная память (Paging)
+- [ ] Файловая система
+- [ ] Многозадачность
+- [ ] Пользовательский режим
+- [ ] Сетевой стек
+
+## Требования
+
+Для сборки и запуска KintsugiOS необходим следующий инструментарий:
+
+- [Кросс-компилятор i386 ELF GCC](http://newos.org/toolchains/i386-elf-15.1.0-Linux-x86_64.tar.xz)
+- FASM 1.73.31 или новее
+- NASM 2.16 или новее
+- GDB для отладки
+- MTools и Xorriso для создания образов дисков
+- QEMU или Bochs для эмуляции
+
+Проверить готовность окружения можно скриптом:
+```bash
+./check-env.sh
+```
 
-Пожалуйста, скачайте тулчейн компилятора и переместите его в директорию `toolchain/`. Также вы можете изменить `shell.nix`:
+## Структура проекта
 
-```nix
-let
-  customToolchainPath = "toolchain/i386-elf-15.1.0-Linux-x86_64/bin"; # ваш путь до бинарников компилятора
-in
+```
+src/
+├── bootloader/           # Код загрузчика
+│   ├── bootsector.asm    # Главная загрузочная запись
+│   ├── diskload.asm      # Чтение с диска
+│   ├── gdt.asm           # Глобальная таблица дескрипторов
+│   ├── kernel_entry.asm  # Точка входа в ядро
+│   ├── puts_chars.asm    # Вывод текста (16-бит)
+│   ├── puts_chars32.asm  # Вывод текста (32-бит)
+│   ├── puts_hex.asm      # Вывод hex-чисел
+│   └── switch_to32.asm   # Переход в защищённый режим
+└── kernel/               # Ядро ОС
+    ├── cpu/              # Центральные модули процессора
+    │   ├── idt.[ch]      # Таблица дескрипторов прерываний
+    │   ├── interrupt.asm # Обработчики прерываний
+    │   ├── isr.[ch]      # Службы прерываний
+    │   ├── ports.[ch]    # Работа с портами ввода-вывода
+    │   ├── timer.[ch]    # Системный таймер
+    │   └── type.h        # Общие типы данных
+    ├── drivers/          # Драйверы устройств
+    │   ├── keyboard.[ch] # Драйвер клавиатуры
+    │   ├── lowlevel_io.[ch] # Низкоуровневый ввод-вывод
+    │   └── screen.[ch]   # Драйвер экрана
+    ├── kernel/           # Основное ядро
+    │   ├── kernel.[ch]   # Главные функции ядра
+    │   ├── utils.[ch]    # Вспомогательные утилиты
+    └── libc/             # Стандартная библиотека C - KKLIBC (Kintsugi Kernel LibC)
+        ├── function.h    # Вспомогательные макросы
+        ├── mem.[ch]      # Управление памятью
+        ├── stdio.[ch]    # Стандартный ввод-вывод
+        └── string.[ch]   # Работа со строками
 ```
 
-Перел разработкой, проверьте вывод `check-env.sh`:
+## Сборка и запуск
 
+### Базовая сборка
 ```bash
- $ ./check-env.sh
-
-KintsugiOS Development Environment Check
-========================================
-
-Cross Compiler Tools:
-[PASS] i386-elf-gcc
-[PASS] i386-elf-ld
-[PASS] i386-elf-objcopy
-
-Assemblers:
-[PASS] FASM
-[PASS] NASM
-
-Emulators:
-[PASS] QEMU i386
-[PASS] Bochs
-
-Utilities:
-[PASS] GDB
-[PASS] MTools
-[PASS] Xorriso
-
-Environment Check Summary:
-==========================
-Total checks: 10
-Passed: 10
-Environment is fully ready for KintsugiOS development!
+make
 ```
 
-## Сборка и запуск
+### Создание образа диска и запуск в QEMU
+```bash
+make run
+```
+
+### Запуск в QEMU с отладкой
+```bash
+make debug
+```
 
+### Очистка проекта
 ```bash
-make # сборка
-make run # сборка и запуск в qemu
+make clean      # Удаление бинарных файлов
+make clean_all  # Полная очистка
 ```
 
-## Фичи
+## Отладка
 
- + bootloader:
-   + gdt
-   + diskload
-   + switch to 32
- + kernel:
-   + drivers
-   + libc
-   + CPU
-   + basic shell
+Для отладки KintsugiOS запустите систему в режиме отладки:
+```bash
+make debug
+```
 
-## Литература, источники
+И подключитесь через ваш дебаггер (например gdb).
 
-По языку ассемблера:
+## Как работает загрузка
 
- + Зубков С. В. «Assembler для DOS, Windows и Unix»
- + [Введение в машинный код](http://wasm.ru/article.php?article=1022001)
- + [Программирование на ассемблере под DOS](http://wasm.ru/article.php?article=1022003)
- + [Введение в ассемблер](https://hackware.ru/?p=8654)
- + [ASCII таблица](https://www.asciitable.com/)
- + [Погружение в ассемблер](https://xakep.ru/2017/09/11/asm-course-1/)
- + [От изучающего ассемблер до взломщика программ](https://wasm.in/attachments/skljarov-i-izuchaem-assembler-za-7-dnej-pdf.2906/)
- + [Руководство по ассемблеру MASM intel x86_64](https://metanit.com/assembler/tutorial/)
+1. **BIOS** загружает первый сектор диска (512 байт) по адресу 0x7C00
+2. **Загрузчик** инициализирует стек, загружает GDT и переключается в защищённый режим
+3. **Ядро** загружается по адресу 0x1000 и получает управление
+4. **Ядро** инициализирует драйверы, менеджер памяти и командную оболочку
 
-По языку Си:
+## Команды оболочки
 
- + Керниган Б., Ритчи Д. «Язык программирования C»
- + Шилдт Г. «Полный справочник по C»
+KintsugiOS включает оболочку "Keramika Shell" со следующими командами:
 
-По устройству операционных систем:
+- `END` - остановка процессора
+- `CLEAR` - очистка экрана
+- `AMALLOC <size>` - выделение памяти (арена)
+- `MALLOC <size>` - выделение памяти (куча)
+- `FREE <address>` - освобождение памяти
+- `INFO` - информация о системе
+- `MEMDUMP` - дамп памяти
+- `ECHO <text>` - вывод текста
+- `HELP` - справка по командам
 
- + Таненбаум Э. «Современные операционные системы»
- + Таненбаум Э. «Операционные системы: Разработка и реализация»
- + Олифер В., Олифер Н. «Сетевые операционные системы»
- + [OSDEV Wiki](http://osdev.org)
+## Литература и источники
 
-По архитектуре ЭВМ:
+### Ассемблер
+- Зубков С. В. «Assembler для DOS, Windows и Unix»
+- [Введение в машинный код](http://wasm.ru/article.php?article=1022001)
+- [Программирование на ассемблере под DOS](http://wasm.ru/article.php?article=1022003)
 
- + Таненбаум Э. «Архитектура компьютера»
- + Гук М. «Аппаратные средства IBM PC. Энциклопедия»
- + Петцольд Ч. «Код. Тайный язык информатики»
+### Язык C
+- Керниган Б., Ритчи Д. «Язык программирования C»
+- Шилдт Г. «Полный справочник по C»
+
+### Операционные системы
+- Таненбаум Э. «Современные операционные системы»
+- Таненбаум Э. «Операционные системы: Разработка и реализация»
+- [OSDEV Wiki](http://osdev.org)
+
+### Архитектура ЭВМ
+- Таненбаум Э. «Архитектура компьютера»
+- Гук М. «Аппаратные средства IBM PC. Энциклопедия»
+
+## Лицензия
+
+KintsugiOS распространяется под лицензией MIT. Подробнее см. в файле LICENSE.
+
+## Вклад в проект
+
+Приветствуются issues и pull requests. Перед внесением изменений пожалуйста:
+1. Обсудите планируемые изменения в issue
+2. Следуйте существующему кодстайлу
+3. Добавляйте комментарии на русском языке
+4. Тестируйте изменения в QEMU и Bochs
+
+## Благодарности
+
+Особая благодарность сообществу OSDev и авторам учебных материалов, указанных в разделе "Литература и источники".
+
+---
+
+<div align="center">
+<sub>Название "Kintsugi" отсылает к японскому искусству восстановления керамики золотым лаком — метафора красоты в несовершенстве и постоянного развития.</sub>
+</div>

docs/img/device_driver0.png

@@ -0,0 +1,45 @@
+# BIOS и ОС | Документация Metalfish OS
+
+## [Главная страница](./index.md)
+
+Когда мы включаем компьютер, он должен каким-то образом загрузить операционную систему. Он может загрузить ее с дискеты, с флэшки, с жесткого диска или с каих-либо других носителей.
+Среда, которую дает нам компьютер вне ОС, может предоставить нам не так уж и много. Например, мы имеем BIOS (англ. Basic Input/Output Software), набор програм которые изначально загружены в памят и инициализированы как только компьютер включается. БИОС предоставляет базовый контроль над важными девайсами компьютера: экран, клавиатура, жесткий диск.
+Чтобы БИОСу загрузить ОС, ему нужно узнать, есть ли ОС на определенном носителе. Для этого он читает первые 512 байтов носителя которые называются загрузочным сектором (англ. boot sector) и если они кончаются магическим числов 0xaa55,то он загружает код бут сектора в память, а процессор его исполняет.
+
+Чтобы дать понять BIOS, что на текущей флэшке, компакт диске или жестком диске расположена ОС, на этом носителе должен быть загрузочный сектор. BIOS узнает загрузочный сектор по "магическому числу" из 2-х байт, равное 0xaa55 (в шестнадцатеричной системе исчисления). Простейший загрузочный сектор в машинном коде выглядит так:
+
+```bin
+ 		e9 fd ff 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 		00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+	   *
+ 		00 00 00 00 00 00 00 00 00 00 00 00 00 00 55 aa
+```
+
+Как видим, последние 2 байта действительно являются "магическим числом". Первые 3 байта являются машинными инструкциями, которые запускают Бесконечный цикл, а остальное просто заполнено нулями т.к. наша программа должна быть размером ровно 512 байт.
+
+Простейший загрузчик на ассембере для nasm реализован ниже:
+
+```asm
+						; Бесконечный цикл:
+loop:					; Определяем метку "loop"
+
+	jmp loop			; Инструкция "jmp" позволяет нам перейти к метке
+						; "loop" (англ. jump - прыжок), т.е. создается
+						; бесконечный цикл.
+
+times 510-($-$$) db 0	; Инструкция "times" заставляет идущую после нее
+						; команду выполняться опредленное количество раз, т.е.
+						; times <кол-во раз> <команда>.
+						; Токен $ высчитывает позицию начала текущей строки,
+						; токен $$ - позицию начала текущей секции.
+						; 510-($-$$) = 510-(2-0) = 508 байт. Чтобы лучше понять
+						; как это работает, рекомендую посмотреть как программа
+						; выглядит в машинном коде с помощью утилиты ghex.
+						; Таким образом мы заполняем пространство нулями (db 0),
+						; приводя нас к 510-му байту.
+						; db расшифровывается как "declare bytes", т.е.
+						; "объявить байты"
+
+dw 0xaa55				; В последние два байта кладем "магическое число",
+						; чтобы BIOS знал, что это загрузочный сектор
+```