Документация проекта AtlasOS

2026-06-14 01:17:37 +03:00
parent db99f47077
commit 66d9f8037c
8 changed files with 588 additions and 0 deletions
@@ -0,0 +1,116 @@
+# AtlasOS — Архитектура
+
+AtlasOS — миниатюрная UNIX-подобная операционная система для бортовых компьютеров
+игры **Barotrauma**, построенная на MicroLua-контроллерах. Документ описывает
+полную архитектуру: аппаратный слой, шину, модель памяти, файловую систему,
+систему прав и модель выполнения программ.
+
+> Версия архитектуры: **2.0** (inode-ФС). Прототип CLI: `atlas_os/AtlasOS.lua`.
+
+---
+
+## 1. Цели проекта
+
+- Дать **командную оболочку** (shell) на терминале внутри игры.
+- Реализовать **постоянное хранилище** (файловую систему) поверх компонентов памяти.
+- Поддержать **многопользовательность** в духе Linux: пользователи, группы, права `rwx`.
+- Работать в условиях **жёсткого лимита памяти** компонентов Barotrauma.
+- Оставаться **компактным**: система не должна разрастаться и съедать память,
+  предназначенную для пользовательских данных.
+
+## 2. Ключевые ограничения (платформа Barotrauma + MicroLua)
+
+| Ограничение | Значение | Источник |
+|---|---|---|
+| Контроллеров в системе | до **8** | требование |
+| Пинов на контроллер | **32 входа / 32 выхода** | MicroLua |
+| Ёмкость компонента памяти | **4096 символов UTF-8** | компонент Memory |
+| Типы сигналов на пинах | `integer`, `string`, `color` (`"R,G,B"`) | MicroLua |
+| Модель исполнения | `upd(dt)` каждый кадр **или** событие `inp(pin,val)` | MicroLua |
+| Состояние Lua | **не сохраняется** между раундами | MicroLua |
+
+Из последнего пункта следует фундаментальный принцип: **всё, что должно пережить
+раунд, обязано лежать в компонентах памяти**, а не в Lua-переменных контроллера.
+Lua-состояние используется только как **кэш и регистры** (см. `03-memory-model.md`).
+
+## 3. Декомпозиция на блоки
+
+Система разделена на три функциональных блока. Каждый блок — отдельный физический
+MicroLua-контроллер; блоки общаются по **сигнальной шине** (проводам между пинами).
+
+```
+                         ┌──────────────────────────────┐
+                         │        ТЕРМИНАЛ (экран)       │
+                         │  текст · цвет · ввод · clear  │
+                         └───────────────▲──────────────┘
+                                         │ I/O-провода
+                         ┌───────────────┴──────────────┐
+   ввод пользователя ──▶ │   IOC — I/O Controller        │
+                         │   (блок ввода/вывода)         │
+                         └───────────────▲──────────────┘
+                                         │ шина CMD
+                         ┌───────────────┴──────────────┐
+                         │   CMC — Command Controller    │  ◀── shell, разбор
+                         │   (контроллер команд, «CPU»)  │      команд, сессия
+                         └───────────────▲──────────────┘
+                                         │ шина MEM
+                         ┌───────────────┴──────────────┐
+                         │   MMC — Memory/FS Controller  │  ◀── inode-ФС, MMU,
+                         │   (блок памяти и ФС)          │      LZ4, права
+                         └───────────────▲──────────────┘
+                                         │ линии сегментов
+            ┌────────────┬───────────────┼───────────────┬────────────┐
+        ┌───┴───┐    ┌───┴───┐       ┌───┴───┐        ┌───┴───┐    ┌───┴───┐
+        │ SEG0  │    │ SEG1  │  ...  │ SEGk  │   ...  │ SEGn-1│    │ SEGn  │
+        │система│    │ user  │       │ user  │        │ user  │    │ user  │
+        └───────┘    └───────┘       └───────┘        └───────┘    └───────┘
+                          компоненты памяти (по 4096 симв.)
+```
+
+| Блок | Контроллер | Роль |
+|---|---|---|
+| Ввод/вывод | **IOC** | Терминал: вывод текста, цвет, очистка, чтение строки ввода. |
+| Контроллер команд | **CMC** | Shell: парсинг, диспетчеризация команд, сессия пользователя, права на уровне вызовов. |
+| Память и ФС | **MMC** | MMU + файловая система (inode), сжатие LZ4, выделение блоков, проверка прав на уровне ФС. |
+
+Оставшиеся до 5 контроллеров — **резерв/копроцессоры** (тяжёлые команды,
+параллельные сессии). См. `01-hardware.md`.
+
+## 4. Разделение памяти: система ⇄ пользователь
+
+Адресное пространство хранилища делится на две области (подробно — `03-memory-model.md`):
+
+- **Системная область (kernel space).** Метаданные: суперблок, таблица inode,
+  список свободных блоков, таблица пользователей. Указатели хранятся здесь.
+  Компактна, фиксированного объёма.
+- **Пользовательское пространство (user space).** Содержимое файлов, сжатое **LZ4**
+  и закодированное в безопасный текст (Base64 по умолчанию, BMP-упаковка как опция).
+
+Принцип: **«указатели — в системе, данные — у пользователя»**. Контроллеры держат
+в Lua только указатели/индексы и небольшие кэши, а объёмные строки живут в
+сегментах пользовательского пространства и подгружаются по требованию.
+
+## 5. Карта документов
+
+| Файл | Содержание |
+|---|---|
+| [`01-hardware.md`](01-hardware.md) | Компоненты, пины, типы сигналов, распределение контроллеров, физическая топология. |
+| [`02-bus-protocol.md`](02-bus-protocol.md) | Протокол обмена между IOC↔CMC↔MMC по пинам: кадры, опкоды, коды ошибок. |
+| [`03-memory-model.md`](03-memory-model.md) | Адресное пространство, сегменты, указатели, блочное выделение, LZ4 и кодирование. |
+| [`04-filesystem.md`](04-filesystem.md) | inode-ФС: суперблок, формат inode, каталоги, аллокатор блоков, сериализация. |
+| [`05-users-permissions.md`](05-users-permissions.md) | Пользователи, группы, режим `rwx`, аутентификация, проверка прав. |
+| [`06-execution-model.md`](06-execution-model.md) | Контроллер команд, оболочка, модель программы и процесса, копроцессоры. |
+| [`07-command-set.md`](07-command-set.md) | Спецификация команд `ls`, `ls -l`, `ls -la`, `cat`, `cd` и правила расширения. |
+
+## 6. Глоссарий
+
+| Термин | Значение |
+|---|---|
+| **IOC / MMC / CMC** | Три блочных контроллера (I/O, Память/ФС, Команды). |
+| **Сегмент (SEG)** | Один компонент памяти Barotrauma, ёмкость `SEG_SIZE = 4096` символов. |
+| **Блок (block)** | Логическая единица хранения данных файла внутри сегмента (`BLOCK_SIZE` символов). |
+| **inode** | Запись метаданных одного объекта ФС (тип, права, владелец, размер, список блоков). |
+| **Системная область** | Сегменты/поля с метаданными ФС и указателями. |
+| **Пользовательское пространство** | Сегменты с содержимым файлов (сжатым LZ4). |
+| **Шина (bus)** | Набор пинов-проводов между контроллерами для обмена сообщениями. |
+| **Сессия** | Текущий контекст shell в CMC: uid/gid, рабочий каталог (cwd), окружение. |