From 66d9f8037cd512f596afa878d993cf3bc09b6f33 Mon Sep 17 00:00:00 2001 From: SlavaVlad Date: Sun, 14 Jun 2026 01:17:37 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA?= =?UTF-8?q?=D1=82=D0=B0=20AtlasOS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- atlas_os/docs/01-hardware.md | 83 ++++++++++++++++++ atlas_os/docs/02-bus-protocol.md | 70 ++++++++++++++++ atlas_os/docs/03-memory-model.md | 62 ++++++++++++++ atlas_os/docs/04-filesystem.md | 71 ++++++++++++++++ atlas_os/docs/05-users-permissions.md | 60 +++++++++++++ atlas_os/docs/06-execution-model.md | 55 ++++++++++++ atlas_os/docs/07-command-set.md | 71 ++++++++++++++++ atlas_os/docs/README.md | 116 ++++++++++++++++++++++++++ 8 files changed, 588 insertions(+) create mode 100644 atlas_os/docs/01-hardware.md create mode 100644 atlas_os/docs/02-bus-protocol.md create mode 100644 atlas_os/docs/03-memory-model.md create mode 100644 atlas_os/docs/04-filesystem.md create mode 100644 atlas_os/docs/05-users-permissions.md create mode 100644 atlas_os/docs/06-execution-model.md create mode 100644 atlas_os/docs/07-command-set.md create mode 100644 atlas_os/docs/README.md diff --git a/atlas_os/docs/01-hardware.md b/atlas_os/docs/01-hardware.md new file mode 100644 index 0000000..efcd843 --- /dev/null +++ b/atlas_os/docs/01-hardware.md @@ -0,0 +1,83 @@ +# 01 — Аппаратный слой (Hardware) + +## 1. Физические компоненты + +AtlasOS использует следующие компоненты Barotrauma + MicroLua: + +| Компонент | Кол-во | Назначение | Ёмкость / пины | Примечание | +|---|---|---|---|---| +| **MicroLua** | 3 (+5 резерв) | **IOC, CMC, MMC** | 32 in / 32 out | контроллеры блоков | +| **Memory** | n (≥2) | сегменты **SEG0..SEGn** | 4096 символов UTF-8 | хранилище | +| **Terminal / Display** | n | экраны | — | по одному IOC на терминал, login/logout per-terminal | + +Дополнительно: + +- Кнопки / переключатели — источники ввода команд. +- Memory-компоненты подключаются к MMC по **WE- и RD-линиям** (подробно ниже). + +## 2. Распределение контроллеров + +| Контроллер | Роль | Входы (примеры) | Выходы (примеры) | +|---|---|---|---| +| **IOC** (n шт.) | терминал + login | in1 = ввод строки | out1 = текст, out2 = clear, out3 = цвет | +| **CMC** (1) | центральный CPU, shell | сообщения от IOC | команды к IOC и MMC (однонаправленно) | +| **MMC** (1) | MMU + inode-ФС | ответы от SEG | WE/RD/DATA к сегментам | + +Оставшиеся до 5 контроллеров: + +- копроцессоры тяжёлых команд (поиск, архивирование); +- параллельные сессии; +- внешние устройства (радио, датчики, логи). + +## 3. Пины и типы сигналов (MicroLua) + +| Тип на пине | Формат | Пример | Использование | +|---|---|---|---| +| integer | `0`, `1`, `-100` | `out[2] = 1` (clear) | флаги, адреса, коды | +| string | UTF-8 | `out[1] = "ls -l"` | тексты, имена файлов, JSON-подобные сообщения шины | +| color | `"R,G,B"` | `"255,0,128"` | цвет текста на терминале | + +**Важно:** строковые сигналы **неэкранированы** по умолчанию. При передаче по шине специализированные символы (`|`, `\n`, `,`) экранируются внутри протокола (см. `02-bus-protocol.md`). + +## 4. Физическая топология (схема пинов) + +``` + Терминал 1 IOC1 Терминал 2 IOC2 + ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ + │экран │◀──────│out1-3 │ │экран │◀──────│out1-3 │ + │ввод │──────▶│in1 │ │ввод │──────▶│in1 │ + └────────┘ └────▲───┘ └────────┘ └────▲───┘ + │ │ + └──────────────┬─────────────────┘ + │ (однонаправленно) + ┌─────────────────▼─────────────────┐ + │ CMC (1) │ + │ центральный CPU │ + └─────────────────▲─────────────────┘ + │ (однонаправленно) + ┌─────────────────▼─────────────────┐ + │ MMC (1) │ + │ память + inode-ФС │ + └─────────────────▲─────────────────┘ + WE/RD/DATA (однонаправленно) + ┌──────────────┬──────────┬─────────────┐ + ┌───┴───┐ ┌───┴───┐ ┌───┴───┐ ┌───┴───┐ + │ SEG0 │ ... │ SEGk │ │SEG n-1│ │ SEGn │ + └───────┘ └───────┘ └───────┘ └───────┘ +``` + +- Сигналы **только** `in → out` (никаких bidirectional пинов между контроллерами). +- Каждый терминал имеет свой IOC — отдельная сессия + login/logout. +- CMC — единственный исполнитель команд (центральный CPU). +- MMC — единственный доступ к памяти. + +См. детальную организацию пинов и протокол в `02-bus-protocol.md`. + +## 5. Ограничения и рекомендации по экономии + +- Каждый SEG несёт ** overhead сериализации** (`|`, `\n`). Минимизируйте мелкие записи. +- Храните **метаданные только в SEG0** (системная область). +- Используйте **агрегированные сообщения шины** (batch) вместо множества мелких пинов. +- Резервные контроллеры подключайте только когда нужно вынести тяжёлые вычисления. + +См. следующие документы для деталей протокола, памяти и ФС. diff --git a/atlas_os/docs/02-bus-protocol.md b/atlas_os/docs/02-bus-protocol.md new file mode 100644 index 0000000..b2388a5 --- /dev/null +++ b/atlas_os/docs/02-bus-protocol.md @@ -0,0 +1,70 @@ +# 02 — Протокол шины (Bus Protocol) + +Между **IOC ↔ CMC ↔ MMC** обмен идёт по **сигнальным проводам** (пины MicroLua). +Сообщения — короткие UTF-8 строки в формате: + +``` +OP|ARG1|ARG2|...|ARGn +``` + +Где: + +- `OP` — опкод (ASCII, регистрозависимый). +- `ARG*` — аргументы, экранированные по правилу ниже. +- Разделитель — `|` (pipe). Внутри аргументов `|` и `\` экранируются как `\|` и `\\`. +- Строка не должна превышать разумный лимит; контроллеры сами усекают при ошибках. + +## 1. Направления и пины шины + +| Шина | Контроллеры | Выделенные пины CMC | Назначение | +|---|---|---|---| +| **CMD** | IOC ↔ CMC | `in_cmd`, `out_cmd` | ввод команд и вывод текста | +| **MEM** | CMC ↔ MMC | `in_mem`, `out_mem` | запросы ФС и ответы | +| **SEG** | MMC ↔ SEG* | `WE[i]`, `RD[i]`, `DATA` | прямой доступ к сегментам | + +## 2. Опкоды CMD (терминал) + +| Опкод | Направление | Аргументы | Описание | +|---|---|---|---| +| `OUT` | CMC → IOC | `text` | вывести текст на терминал | +| `CLR` | CMC → IOC | — | очистить экран (`out[2]=1`) | +| `COL` | CMC → IOC | `R,G,B` | установить текущий цвет | +| `IN` | IOC → CMC | `line` | пользователь ввёл строку | + +## 3. Опкоды MEM (файловая система) + +| Опкод | Направление | Аргументы | Ответ | Описание | +|---|---|---|---|---| +| `STAT` | CMC → MMC | `path` | `inode\|mode\|uid\|gid\|size` | метаданные файла | +| `READ` | CMC → MMC | `path\|offset\|len` | `data` (Base64) | чтение фрагмента | +| `WRITE` | CMC → MMC | `path\|offset\|data` | `OK\|bytes` или `ERR\|code` | запись | +| `LS` | CMC → MMC | `dir` | `name1\|inode1\|...` | список записей каталога | +| `CHDIR` | CMC → MMC | `path` | `OK\|newcwd` или `ERR` | смена cwd (проверка прав) | + +Коды ошибок: `EACCES`, `ENOENT`, `EEXIST`, `ENOSPC`, `EINVAL`. + +## 4. Прямой доступ SEG (MMC ↔ SEG) + +MMC управляет сегментами напрямую по линиям `WE[i]`, `RD[i]`, `DATA`. +Формат сообщений SEG-уровня — внутренний (не по шине), но общий принцип: + +``` +write_enable(i): DATA <- encoded_block; pulse WE[i] +read(i): pulse RD[i]; receive DATA +``` + +CMC никогда не касается SEG напрямую — только через MMC. + +## 5. Тайминги и подтверждения + +- Каждый запрос шины требует **подтверждения** (ответ `OK`/`ERR`) в течение разумного числа кадров. +- CMC может выполнять до **одного активного запроса** на шину одновременно (сериализация). +- При отсутствии ответа — таймаут и ошибка `ETIMEDOUT`. + +## 6. Сериализация и безопасность + +- Все строковые данные экранируются: `|` → `\|`, `\` → `\\`. +- Base64 (или BMP-упаковка) гарантирует, что сжатые данные не содержат управляющих символов. +- Проверяйте длину: при превышении 4096 символов — ошибка. + +Подробности форматов inode, блоков и сжатия — в `03-memory-model.md` и `04-filesystem.md`. diff --git a/atlas_os/docs/03-memory-model.md b/atlas_os/docs/03-memory-model.md new file mode 100644 index 0000000..e46c710 --- /dev/null +++ b/atlas_os/docs/03-memory-model.md @@ -0,0 +1,62 @@ +# 03 — Модель памяти (Memory Model) + +## 1. Адресное пространство + +``` +0x0000 СИСТЕМНАЯ ОБЛАСТЬ (kernel space) + ├─ SEG0 суперблок + inode table + free list + passwd + └─ (опц.) SEG1 (расширение метаданных) + +0x1000+ ПОЛЬЗОВАТЕЛЬСКОЕ ПРОСТРАНСТВО (user space) + ├─ SEG2..SEGk блоки файлов (сжатые LZ4) + └─ ... до SEGn (ограничено 8 контроллерами, n ~ десятки) +``` + +- **SEG0** обязателен и содержит **все указатели**. +- Пользовательские данные (файлы) — **только** в user-сегментах. +- Каждый сегмент — независимый компонент Memory (4096 символов UTF-8). + +## 2. Сегмент (SEG) + +| Поле | Размер | Описание | +|---|---|---| +| `SEG_SIZE` | 4096 | максимум символов UTF-8 | +| `BLOCK_SIZE` | 512 | логический блок внутри сегмента (рекомендация) | +| `BLOCKS_PER_SEG` | 8 | 512 × 8 = 4096 | + +> Можно использовать переменный размер блоков; главное — детерминированная адресация. + +**Адрес блока** кодируется как `uint32 = (seg_idx << 16) | block_idx`. + +## 3. Указатели и сериализация + +Все указатели (номера inode, номера блоков, смещения) хранятся в **SEG0** в компактном ASCII-формате: + +``` +SUPER|version|seg_size|inode_count|root_inode|free_head +INODE|ino|type|mode|uid|gid|size|block0,block1,... +DIR|ino|name→ino|name→ino|... +PASSWD|uid|name|gid|home|hash +``` + +Контроллеры (CMC/MMC) держат в Lua-памяти только **индексы и кэши**, а не целые файлы. + +## 4. Сжатие и кодирование + +| Способ | Плотность | Безопасность | Примечание | +|---|---|---|---| +| **LZ4 + Base64** (по умолчанию) | ~3/4 | 100 % ASCII safe | 4096 симв. → ~3 КБ сжатых данных | +| **LZ4 + BMP-упаковка** (опция) | ~2× | нужно экранирование управляющих | 2 байта → 1 символ | + +- Сжатие применяется **поблочно** (каждый блок файла сжимается отдельно). +- При Base64 длина сжатого блока должна быть кратна 3 байтам. +- Декодирование и распаковка — задача MMC при чтении/записи. + +## 5. Экономия памяти (рекомендации) + +- Храните **только метаданные** в SEG0; содержимое файлов — в user-сегментах. +- Используйте **агрегированные free-list** вместо bitmap (экономит поле на сегмент). +- Избегайте мелких файлов — они дают overhead inode + минимум 1 блок. +- При чтении подгружайте **только нужные блоки**, не весь файл целиком. + +Следующий документ: `04-filesystem.md` — точные форматы inode, каталогов и free-list. diff --git a/atlas_os/docs/04-filesystem.md b/atlas_os/docs/04-filesystem.md new file mode 100644 index 0000000..9853e70 --- /dev/null +++ b/atlas_os/docs/04-filesystem.md @@ -0,0 +1,71 @@ +# 04 — Файловая система (inode-based FS) + +## 1. Суперблок (SEG0, первая строка) + +``` +SUPER|v1|4096|256|1|free_head +``` + +Поля: + +- `version` — строка формата. +- `seg_size` — 4096. +- `inode_count` — максимум inode. +- `root_inode` — обычно 1 (`/`). +- `free_head` — первый свободный блок (или 0 если нет). + +## 2. Формат inode + +``` +INODE|ino|type|mode|uid|gid|size|mtime|block0,block1,...|next_ino +``` + +| Поле | Тип | Описание | +|---|---|---| +| `ino` | int | номер inode (1..inode_count) | +| `type` | `f`/`d`/`l` | файл / каталог / симлинк | +| `mode` | octal | 12-бит rwxrwxrwx + suid/sgid | +| `uid`/`gid` | int | владелец и группа | +| `size` | int | размер в байтах (несжатый) | +| `mtime` | int | unix-time последнего изменения | +| `block*` | list | список адресов блоков (см. 03) | +| `next_ino` | int | цепочка свободных inode (0 = конец) | + +> inode сериализуется в одну строку; длина ограничена 4096. + +## 3. Каталоги + +Каталог — inode типа `d`. Содержимое — пары `name→ino`, сериализуются как: + +``` +DIR|ino|name1→ino1|name2→ino2|... +``` + +- Имена не содержат `/` и `|`. +- `.` и `..` хранятся явно. + +## 4. Блоки и free list + +- Каждый блок адресуется как `(seg_idx<<16)|block_idx`. +- Free list — односвязный список: `free_head → block → ... → 0`. +- `free_head` хранится в суперблоке. +- При выделении/освобождении MMC обновляет `next_block` указатель внутри строки блока (первые 8 символов — `"NEXT|xxxx"`). + +## 5. Операции ФС (минимум) + +| Операция | Действие MMC | +|---|---| +| `STAT path` | найти inode, вернуть поля | +| `READ path off len` | найти блоки, склеить, Base64-декодировать, LZ4-распаковать, вернуть фрагмент | +| `WRITE path off data` | найти/выделить блоки, сжать, записать, обновить size/mtime | +| `LS dir` | прочитать DIR-запись, вернуть список | +| `CHDIR path` | проверить `x` право, обновить cwd сессии | + +## 6. Ограничения и экономия + +- inode_count ≤ 256 (чтобы таблица влезала в SEG0). +- BLOCK_SIZE = 512 → 8 блоков на сегмент. +- Маленькие файлы (< 1 блока) упаковываются в один блок; остаток — slack. +- Метаданные (inode, DIR, free list) — **только** в SEG0. + +См. `05-users-permissions.md` для формата passwd и проверок прав. diff --git a/atlas_os/docs/05-users-permissions.md b/atlas_os/docs/05-users-permissions.md new file mode 100644 index 0000000..f216656 --- /dev/null +++ b/atlas_os/docs/05-users-permissions.md @@ -0,0 +1,60 @@ +# 05 — Пользователи и права (Users & Permissions) + +## 1. Хранилище пользователей (SEG0) + +``` +PASSWD|uid|name|gid|home|hash +``` + +Пример: + +``` +PASSWD|0|root|0|/|- +PASSWD|100|captain|10|/home/captain|abc123hash +PASSWD|101|engineer|20|/home/engineer|def456hash +``` + +- `uid` / `gid` — положительные целые. +- `hash` — простой хеш пароля (не криптографический, только для игровых целей). +- Минимальный набор: `root` (uid=0) и хотя бы один пользователь. + +## 2. Права доступа (mode bits) + +``` +rwxrwxrwx (9 бит) + suid/sgid (2 бита) = 12-бит octal +``` + +| Бит | Название | Проверка | +|---|---|---| +| `0400` | `r` owner | uid == file.uid | +| `0200` | `w` owner | uid == file.uid | +| `0100` | `x` owner | uid == file.uid | +| `0040..0010` | `rwx` group | gid == file.gid | +| `0004..0001` | `rwx` other | всегда | +| `4000` | suid | (не используется в командах ls/cat) | +| `2000` | sgid | (не используется) | + +## 3. Проверка прав (MMC) + +При каждом `STAT/READ/WRITE/LS/CHDIR` MMC: + +1. Получает `uid/gid` из сессии CMC. +2. Загружает inode файла/каталога. +3. Вычисляет effective mode: + - если uid == 0 (root) — полный доступ; + - иначе комбинирует owner/group/other биты. +4. Возвращает `EACCES` при отказе. + +## 4. Аутентификация + +- Простейшая: `login name pass` сравнивает хеш. +- Сессия CMC хранит текущие `uid/gid`. +- `su` / `logout` — опциональные команды (см. `07-command-set.md`). + +## 5. Экономия + +- Таблица `PASSWD` ≤ 32 записи (чтобы влезала в SEG0). +- Хеш — короткая строка (8–16 символов). +- Права проверяются **только** при операциях ФС; CMC не дублирует проверки. + +См. `06-execution-model.md` — как сессия хранит uid/gid и cwd. diff --git a/atlas_os/docs/06-execution-model.md b/atlas_os/docs/06-execution-model.md new file mode 100644 index 0000000..c8ec77b --- /dev/null +++ b/atlas_os/docs/06-execution-model.md @@ -0,0 +1,55 @@ +# 06 — Модель выполнения (Execution Model) + +## 1. Роли контроллеров + +| Контроллер | Что хранит в Lua | Что делает | +|---|---|---| +| **IOC** (n шт.) | цвет, буфер вывода, текущий пользователь | вывод на терминал, clear, приём ввода, login/logout | +| **CMC** (1) | таблица предопределённых команд, сессии | парсинг, выполнение только встроенных команд, вызовы MMC | +| **MMC** (1) | кэш inode (опц.), free list head | операции ФС, сжатие/распаковка, проверка прав | + +## 2. Сессия (в CMC) + +``` +session = { + uid = 100, + gid = 10, + cwd = "/home/captain", + env = { PATH = "/bin:/usr/bin" } +} +``` + +- Сессия создаётся при `login`. +- `cwd` обновляется командой `cd` (MMC проверяет `x`). +- uid/gid передаются в каждый MEM-запрос. + +## 3. Модель команд + +- Контроллеры выполняют **только предопределённые команды**, зашитые в прошивку (Lua-код контроллера). +- Пользователь **не может** выполнять произвольный Lua-код. +- Доступные команды: `ls`, `ls -l`, `ls -la`, `cat`, `cd`, `login`, `logout` и другие, зарегистрированные в CMC. +- Каждая команда — жёстко заданная функция в firmware CMC. + +## 4. Копроцессоры (опционально) + +Оставшиеся 5 контроллеров могут выполнять: + +- тяжёлые команды (`find`, `grep`, архивация); +- фоновые задачи (логи, мониторинг); +- параллельные сессии нескольких пользователей. + +Связь — по той же шине MEM/CMD. + +## 5. Очередь и сериализация + +- CMC допускает **только один активный MEM-запрос** одновременно. +- Следующая команда ждёт ответа `OK`/`ERR`. +- При отсутствии ответа — таймаут и ошибка. + +## 6. Экономия памяти Lua + +- Храните в сессии только **скаляры** (cwd — строка пути, uid/gid — числа). +- Буферы файлов и большие таблицы — **только** в SEG (MMC). +- Избегайте рекурсии и больших локальных таблиц в командах. + +См. `07-command-set.md` — конкретные команды и их аргументы. diff --git a/atlas_os/docs/07-command-set.md b/atlas_os/docs/07-command-set.md new file mode 100644 index 0000000..e0129ff --- /dev/null +++ b/atlas_os/docs/07-command-set.md @@ -0,0 +1,71 @@ +# 07 — Набор команд (Command Set) + +## 1. Базовые правила + +- Команды регистрируются в CMC через `register(name, func, desc)`. +- Аргументы — таблица строк после парсинга `gmatch("%S+")`. +- Вывод — через `print(text)` (цвет текущий) или `printerror(text)`. +- Ошибки возвращаются как `error("msg")` — перехватываются `pcall`. + +## 2. Обязательные команды (минимум v2.0) + +### `ls [path]` + +- Выводит список имён в cwd (или `path`). +- Без `-l` — только имена, по одному на строку. + +### `ls -l [path]` + +- Длинный формат: `type mode uid gid size mtime name`. +- Пример: `d rwxr-xr-x 0 0 4096 1712345678 bin` + +### `ls -la [path]` + +- То же, что `-l`, плюс скрытые файлы (начинающиеся с `.`). + +### `cat path` + +- Выводит содержимое файла (распакованное). +- При ошибке (нет прав, нет файла) — `printerror`. + +### `cd [path]` + +- Меняет cwd сессии. +- MMC проверяет право `x` на каталоге. +- `cd` без аргумента → `$HOME` пользователя. + +## 3. Выходной формат `ls -l` + +``` +type perms uid gid size mtime name +f rw-r--r-- 100 10 1234 1712345678 readme.txt +d rwxr-xr-x 0 0 0 1712345678 bin +``` + +## 4. Расширяемость + +- Новые команды добавляются регистрацией в `commands`. +- Имя — одно слово, без пробелов. +- Описание — краткая строка для `help`. +- Примеры: `login`, `su`, `logout`, `echo`, `clear`, `color`, `help`, `status`. + +## 5. Примеры ошибок + +| Ситуация | Сообщение | +|---|---| +| Нет файла | `cat: /foo: No such file or directory` | +| Нет прав | `ls: /secret: Permission denied` | +| Неизвестная команда | `Error: Unknown command. Type 'help' for list.` | + +## 6. Совместимость с прототипом + +Текущий `AtlasOS.lua` уже реализует `help`, `echo`, `clear`, `color`, `status`. +Новые команды (`ls*`, `cat`, `cd`) добавляются по той же схеме: + +```lua +register_command("ls", function(args) ... end, "List directory") +``` + +--- + +**Конец комплекта документации v2.0** diff --git a/atlas_os/docs/README.md b/atlas_os/docs/README.md new file mode 100644 index 0000000..8919a10 --- /dev/null +++ b/atlas_os/docs/README.md @@ -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), окружение. |