feat: docs & ARCH 2.2, 2.3, 2.4

kernel/docs/capability/objects.md

@@ -0,0 +1,73 @@
+# Ядерные объекты: `object.rs`
+
+## Концептуальная модель
+
+`KernelObject` — это ref-counted представление объекта ядра.
+В отличие от `Capability` (которая указывает на объект), `KernelObject`
+— это сам объект с подсчётом ссылок.
+
+## Структура
+
+```rust
+pub struct KernelObject {
+    pub phys_addr: PhysAddr,     // физический адрес объекта
+    pub size_bits: u8,           // размер в битах (2^size_bits)
+    pub obj_type: ObjectType,    // тип объекта
+    pub ref_count: AtomicUsize,  // счётчик ссылок
+    pub owner_id: u64,           // ID владельца
+}
+```
+
+## ObjectType — классификация объектов
+
+```rust
+pub enum ObjectType {
+    Untyped,      // Сырая память без типа
+    Frame,        // Фрейм (4KiB страница)
+    CNode,        // Capability Node
+    ThreadBlock,  // Блок управления потоком (TCB)
+    PageTable,    // Таблица страниц
+}
+```
+
+## Ref-counting
+
+```rust
+impl KernelObject {
+    pub fn add_ref(&self) {
+        self.ref_count.fetch_add(1, Ordering::Relaxed);
+        // ^ Relaxed: нас не волнует порядок других операций
+        // при увеличении счётчика. Только атомарность.
+    }
+
+    pub fn release(&self) -> bool {
+        self.ref_count.fetch_sub(1, Ordering::Release) == 1
+        // ^ Release: все операции до release видны тому,
+        // кто Acquire-читает ref_count.
+        // Возвращает true, если это была последняя ссылка
+        // (объект должен быть уничтожен).
+    }
+}
+```
+
+## Текущее состояние
+
+`KernelObject` определён, но пока не используется активно.
+Capability-система в текущей версии работает напрямую с `CapObject`
+и `PhysAddr`, без обёртки в `KernelObject`.
+
+Планируемое использование:
+- При выделении памяти через PMActor: создаётся KernelObject.
+- Capability ссылается на KernelObject через ID/индекс.
+- Когда последняя Strong capability удалена → KernelObject
+  уничтожается → память возвращается.
+
+## Отличие CapObject vs KernelObject
+
+| Характеристика | CapObject | KernelObject |
+|---------------|-----------|--------------|
+| Роль | Что capability представляет | Сам объект в памяти ядра |
+| Ref-count | Нет | AtomicUsize |
+| Хранение | В CNode slot | В отдельной таблице |
+| Типы | Memory, CNode, PMActor | Untyped, Frame, CNode, ThreadBlock, PageTable |
+| Связь | CapObject.Memory.phys = KernelObject.phys_addr | — |