feat: docs & ARCH 2.2, 2.3, 2.4

kernel/docs/capability/descriptors.md

@@ -0,0 +1,115 @@
+# Дескрипторы capability: `descriptor.rs`
+
+## Назначение
+
+Файл определяет базовые типы capability-системы:
+что такое capability, какие бывают объекты, права и отношения.
+
+## CapObject — что представляет capability
+
+```rust
+pub enum CapObject {
+    Empty,                              // Пустой слот
+    Memory { phys: PhysAddr, size_pages: usize },  // Фрейм памяти
+    CNode { phys: PhysAddr, slots: usize },         // Другой CNode
+    PMActor { id: u64 },                             // PM Actor
+}
+```
+
+### Memory
+
+Capability на физическую память:
+- `phys` — физический адрес начала.
+- `size_pages` — размер в страницах.
+
+### CNode
+
+Capability на другой CNode:
+- `phys` — физический адрес CNode.
+- `slots` — количество слотов.
+
+### PMActor
+
+Capability на PMActor:
+- `id` — уникальный идентификатор актора.
+
+### Empty
+
+Слот пуст. `is_valid()` возвращает `false`.
+
+## CapRights — права доступа
+
+```rust
+bitflags! {
+    pub struct CapRights: u8 {
+        const READ    = 1 << 0;  // 0x01 — чтение
+        const WRITE   = 1 << 1;  // 0x02 — запись
+        const EXECUTE = 1 << 2;  // 0x04 — исполнение
+        const GRANT   = 1 << 3;  // 0x08 — разрешение на mint
+    }
+}
+```
+
+**Правила:**
+- Права дочернего capability = `родительские_права & запрошенные_права`.
+- Нельзя расширить права: если родитель не имеет GRANT, mint невозможен.
+- `CapRights::all()` = R | W | X | G = 0x0F.
+
+## Relation — тип связи
+
+```rust
+pub enum Relation {
+    Strong,   // Владелец — сильная ссылка (объект жив, пока есть Strong)
+    Borrow,   // Заёмщик — временный доступ
+    Transfer, // Передача — владение переходит без возможности отзыва
+}
+```
+
+- **Strong**: capability владеет объектом. При revoke, объект может
+  быть уничтожен или возвращён пулу.
+- **Borrow**: capability предоставляет временный доступ.
+  При revoke родителя, borrow-потомки тоже отзываются.
+- **Transfer**: полная передача владения. Используется при IPC.
+
+## Capability — полный дескриптор
+
+```rust
+#[derive(Debug, Clone, Copy)]
+pub struct Capability {
+    pub object: CapObject,    // Целевой объект
+    pub rights: CapRights,    // Права доступа
+    pub relation: Relation,   // Тип связи
+    pub token_sig: u64,       // Уникальный подписывающий токен
+}
+```
+
+### token_sig — назначение
+
+- Уникальный 64-битный идентификатор capability.
+- Используется для:
+  1. **Отзыва**: при revoke, token_sig отправляется в MMU_REVOCATION_QUEUE.
+  2. **Идентификации в VMM**: VMA хранят `cap_token == token_sig`.
+  3. **Отладки**: каждый capability можно однозначно отследить.
+
+### Методы
+
+```rust
+impl Capability {
+    pub const fn empty() -> Self {
+        Self {
+            object: CapObject::Empty,
+            rights: CapRights::empty(),
+            relation: Relation::Borrow,
+            token_sig: 0,
+        }
+    }
+
+    pub fn is_valid(&self) -> bool {
+        !matches!(self.object, CapObject::Empty)
+    }
+}
+```
+
+`token_sig = 0` зарезервирован для пустых/невалидных capability.
+`token_sig = 0xDEAD_BEEF` используется для сырых Untyped
+(не отправляется в MMU_REVOCATION_QUEUE, см. `cap/mod.rs`).