# Дескрипторы 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`).