update readme

Author: alexeev-prog

CHANGELOG.md

@@ -1,3 +1,9 @@
+commit 7e10152d363ffbde636a316c6da7d99f0257f5ec
+Author: Alexeev Bronislav <[email protected]>
+Date:   Mon Sep 1 01:11:27 2025 +0700
+
+    small update for util scripts
+
 commit 3f710e02f6bc2fd28d65b73e38dc8061b36d3d2c
 Author: Alexeev Bronislav <[email protected]>
 Date:   Sun Aug 31 22:32:14 2025 +0700

README.md

@@ -165,6 +165,67 @@ KintsugiOS включает оболочку "Keramika Shell" со следую
 - `binpow <base> <exponent>` - бинарное возведение в степень
 - `fib <num>` - алгоритм фибоначчи
 
+## Kintsugi Kernel LibC
+KKLibc — это собственная реализация стандартной библиотеки языка C, разработанная специально для нужд ядра Kintsugi OS. В отличие от пользовательских libc (вроде glibc), она тесно интегрирована с архитектурой ядра, лишена избыточности и содержит только самые необходимые функции для работы в пространстве ядра.
+
+**Структура и основные модули:**
+
+Библиотека организована в набор модулей, каждый из которых отвечает за свою предметную область:
+
+ + **`stdlib.h` / `stdlib.c`**: Ядро библиотеки. Содержит:
+     + **Преобразования данных:** `itoa`, `utoa`, `atoi`, `hex_strtoint` для конвертации между числами и строками в различных системах счисления.
+     + **Работа со строками:** Полный набор функций для манипуляций со строками: `strlen`, `strcpy`/`strncpy`, `strcmp`/`strncmp`, `strcat`/`strncat`, `strchr`, `strstr`, `strtok`, `strspn`, `strcspn`.
+     + **Работа с памятью:** Аналоги стандартных `memcpy`, `memset`, `memmove`, `memcmp`, `memchr`, а также низкоуровневые `memory_set`, `u32memory_set`.
+     + **Генерация псевдослучайных чисел:** Реализация на основе быстрого алгоритма `xorshift32` (`rand`) и функция для получения числа в диапазоне (`rand_range`).
+     + **Управление системой:** Функции `reboot()` и `wait(int ms)` для взаимодействия с железом.
+     + **Форматированный вывод в буфер:** Реализации `sprintf`, `snprintf` и `vsnprintf` для безопасного и небезопасного формирования строк.
+     + *Утилиты:* Алгоритм нечеткого поиска `fuzzy_search` для будущего использования в интерфейсах.
+
+ + **`stdio.h` / `stdio.c`**: Модуль форматированного вывода. Реализует функции `printf`, `printf_colored` и `printf_at`, которые напрямую взаимодействуют с драйвером экрана (`screen.h`), обеспечивая вывод текста в заданном месте и цвете.
+
+ + **`mem.h` / `mem.c`**: **Менеджер памяти (кучи) ядра.** Реализует динамическое выделение памяти внутри ядра.
+     + **Аллокатор:** Использует алгоритм с разделением и слиянием свободных блоков памяти для минимизации фрагментации.
+     + **Интеграция с Paging:** Функция `expand_heap` динамически запрашивает новые физические страницы через менеджер виртуальной памяти (`paging.h`) при нехватке памяти в куче, что делает кучу по-настоящему расширяемой.
+     + **API:** Предоставляет знакомые API: `kmalloc`, `kfree`, `krealloc`.
+     + **Отладка:** Содержит функции для отладки и мониторинга состояния кучи: `kmemdump`, `get_meminfo`.
+
+ + **`paging.h` / `paging.c`**: **Менеджер виртуальной памяти.** Один из самых низкоуровневых и критичных модулей.
+     + Организует 4-гигабайтное виртуальное адресное пространство ядра.
+     + Реализует механизм страничной адресации x86 с двумя уровнями таблиц (Page Directory и Page Table).
+     + Предоставляет функции для выделения (`alloc_frame`) и освобождения (`free_frame`) физических кадров памяти.
+     + Содержит обработчик исключения Page Fault.
+     + Предоставляет интерфейс `pkmalloc` для выделения выровненных по странице блоков памяти с возможностью получения физического адреса, что необходимо для работы с DMA и другими hardware.
+
+ + **`math.h` / `math.c`**: Набор математических функций и алгоритмов, включая вычисление чисел Фибоначчи, бинарное возведение в степень, факториал и дискриминант.
+
+ + **`ctypes.h` / `ctypes.c`**: Полная реализация стандартных функций классификации и преобразования символов (`isalpha`, `isdigit`, `toupper`, etc.).
+
+ + **`datatypes/vector.h` / `vector.c`**: Реализация динамического массива (вектора) — фундаментальной структуры данных, которая будет полезна для управления списками процессов, дескрипторов файлов и т.д.
+
+ + **`kklibc.h`**: Главный заголовочный файл, который включает все модули библиотеки для удобства.
+
+**Философия дизайна:**
+
+ + **Префиксы `k` и `p`:** Префикс `k` (например, `kmalloc`) означает принадлежность к ядру (kernel) и его куче. Префикс `p` (например, `pkmalloc`) означает работу с низкоуровневой страничной памятью (paging).
+ + **Самостоятельность:** Библиотека минимально зависима от внешнего кода, что является обязательным требованием для кода ядра.
+ + **Производительность над избыточностью:** Функции реализованы с оглядкой на скорость и минимальный расход памяти, а не на абсолютную совместимость со стандартом.
+
+KKLibc является живым, развивающимся проектом и продолжает обрастать новыми функциями и оптимизациями по мере развития самой Kintsugi OS.
+
+---
+
+### Планы на будущее для KKLibc
+
+ + **Решение проблем с кучей:** Текущая архитектура с двумя аллокаторами (`kmalloc` и `pkmalloc`) мощная, но требует доработки для полной стабильности. Основная задача — **устранить все возможные scenarious повреждения кучи**, особенно в моменты, когда `kmalloc` вызывает `expand_heap`, который, в свою очередь, через `pkmalloc` и `alloc_frame` запрашивает новые физические страницы. Необходимо тщательно протестировать это взаимодействие на предмет race condition и корректности обновления внутренних структур данных аллокатора.
+ + **Внедрение кананингов (Canaries):** Для отладки повреждения кучи планируется добавить механизм "канареек" — специальных значений, размещаемых вокруг выделенных блоков памяти. При освобождении памяти или в отладочной сборке будет проверяться целостность этих канареек, что позволит сразу обнаружить операции записи за пределами выделенного блока (buffer overflow).
+ + **Отладочный аллокатор:** Реализация специальной версии `kmalloc`, которая ведет логи всех операций выделения/освобождения памяти (с указанием размера, адреса и callstack'а). Это незаменимый инструмент для поиска утечек памяти (memory leaks) в ядре.
+ + **Планировщик и синхронизация:** Когда будет реализован планировщик задач и многозадачность, **критически важным станет сделать аллокатор потокобезопасным**. Это потребует добавления механизмов синхронизации (спинлоков или мьютексов) внутрь функций `kmalloc` и `kfree`.
+ + **Поддержка пользовательского пространства:** В будущем, когда появится разграничение на режим ядра и пользовательский режим, KKLibc будет разделена. Большая часть останется в ядре, а для пользовательского пространства будет создана отдельная, возможно, урезанная и более безопасная версия библиотеки.
+ + **Оптимизация производительности:** Постоянный процесс: переписывание ключевых функций (например, `memcpy`, `memset`) на ассемблере для максимальной скорости, внедрение более эффективных алгоритмов поиска свободных блоков памяти.
+ + **Новые модули:** По мере необходимости будут добавляться новые структуры данных (связные списки, хэш-таблицы), функции для работы со строками в кодировке UTF-8 и другие утилиты, требуемые развивающейся операционной системой.
+
+Развитие KKLibc напрямую связано с развитием Kintsugi OS. Каждый новый системный вызов, драйвер или компонент ядра будет опираться на ее надежное и эффективное API.
+
 ## Литература и источники
 
 ### Ассемблер
@@ -175,6 +236,7 @@ KintsugiOS включает оболочку "Keramika Shell" со следую
 ### Язык C
 - Керниган Б., Ритчи Д. «Язык программирования C»
 - Шилдт Г. «Полный справочник по C»
+- [C standard library for embedded systems](https://github.com/peterzuger/libc)
 
 ### Операционные системы
  - Таненбаум Э. «Современные операционные системы»