# amineux/aether architecture

> Architecture diagram of the GitHub repository amineux/aether, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amineux/aether
- Repository: https://github.com/amineux/aether

## Overview

Aether is a research accelerator-first fabric kernel: user processes submit capability-checked messages and accelerator jobs, which the kernel routes to fabric and compute services and reports through waits/completions. Boot loads `/init`; the kernel supplies address spaces, scheduling, and syscall dispatch. Major documented branches include tenant isolation, Soft-SMMU/SVA, command-processor and SoftNPU models, synchronization, partitioning, and KV grants. Several branches are documented but unsampled, so their internal links are omitted or marked unverified.

Main entry points: [`kernel/src/world.rs`](https://github.com/amineux/aether/blob/main/kernel/src/world.rs) (Kernel objects), [`kernel/src/syscall.rs`](https://github.com/amineux/aether/blob/main/kernel/src/syscall.rs) (Syscall gate), [`core/src/accel.rs`](https://github.com/amineux/aether/blob/main/core/src/accel.rs) (Accelerator jobs), [`kernel/src/elfload.rs`](https://github.com/amineux/aether/blob/main/kernel/src/elfload.rs) (ELF and bootfs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and execution"]
  node_entry["Kernel entry<br/>[main.rs]"]
  node_loader["ELF and bootfs<br/>[elfload.rs]"]
  node_inituser["Init process<br/>[main.rs]"]
  node_probe["Probe process<br/>[main.rs]"]
end

subgraph group_kernel["Kernel services"]
  node_syscall["Syscall gate<br/>[syscall.rs]"]
  node_world["Kernel objects<br/>[world.rs]"]
  node_memory["Address spaces<br/>[paging.rs]"]
  node_tasks["Threads and scheduler<br/>[task.rs]"]
end

subgraph group_fabric["Fabric and isolation"]
  node_caps["Capabilities<br/>[caps.rs]"]
  node_fabriccore["Message fabric<br/>[fabric.rs]"]
  node_arena["Tensor arenas<br/>[arena.rs]"]
  node_isolation["Blast isolation<br/>[blast.rs]"]
  node_smmu["Soft SMMU<br/>[iommu.rs]"]
end

subgraph group_compute["Accelerator execution"]
  node_partition["Tile partitioning<br/>[partition.rs]"]
  node_sync["Chiplet synchronization<br/>[chipsync.rs]"]
  node_kv["KV fabric grants<br/>[kvfabric.rs]"]
  node_softsfi["SoftSFI sandbox<br/>[softsfi.rs]"]
  node_injection["Resident op injection<br/>[opinject.rs]"]
  node_accel["Accelerator jobs<br/>[accel.rs]"]
  node_cp["Command processor<br/>[fakecp.rs]"]
  node_softnpu["SoftNPU driver<br/>[softnpu.rs]"]
end

subgraph group_integration["Host and partner interfaces"]
  node_pjrt["PJRT interface<br/>[lib.rs]"]
  node_mp["MP shim<br/>[lib.rs]"]
end

node_app(("User workloads"))

node_entry -->|"loads images"| node_loader
node_entry -->|"spawns tasks"| node_tasks
node_loader -.->|"loads /init"| node_inituser
node_loader -.->|"loads probe"| node_probe
node_inituser -->|"invokes syscalls"| node_syscall
node_probe -.->|"invokes syscalls"| node_syscall
node_syscall -->|"dispatches services"| node_world
node_syscall -->|"maps pages"| node_memory
node_syscall -->|"clones threads"| node_tasks
node_world -->|"sends messages"| node_fabriccore
node_world -.->|"checks rights"| node_caps
node_world -.->|"allocates arenas"| node_arena
node_world -.->|"submits jobs"| node_accel
node_accel -->|"uses profiles"| node_partition
node_cp -.->|"resolves DMA"| node_smmu
node_cp -.->|"executes commands"| node_softnpu
node_accel -.->|"signals completion"| node_sync
node_kv -.->|"grants KV"| node_fabriccore
node_softsfi -.->|"enforces sandbox"| node_isolation
node_injection -.->|"adds operations"| node_accel
node_pjrt -.->|"submits commands"| node_cp
node_mp -.->|"uses interface"| node_pjrt

click node_entry "https://github.com/amineux/aether/blob/main/kernel/src/main.rs"
click node_loader "https://github.com/amineux/aether/blob/main/kernel/src/elfload.rs"
click node_inituser "https://github.com/amineux/aether/blob/main/user/init/src/main.rs"
click node_probe "https://github.com/amineux/aether/blob/main/user/probe/src/main.rs"
click node_syscall "https://github.com/amineux/aether/blob/main/kernel/src/syscall.rs"
click node_world "https://github.com/amineux/aether/blob/main/kernel/src/world.rs"
click node_memory "https://github.com/amineux/aether/blob/main/kernel/src/mm/paging.rs"
click node_tasks "https://github.com/amineux/aether/blob/main/kernel/src/task.rs"
click node_caps "https://github.com/amineux/aether/blob/main/core/src/caps.rs"
click node_fabriccore "https://github.com/amineux/aether/blob/main/core/src/fabric.rs"
click node_arena "https://github.com/amineux/aether/blob/main/core/src/arena.rs"
click node_isolation "https://github.com/amineux/aether/blob/main/core/src/blast.rs"
click node_smmu "https://github.com/amineux/aether/blob/main/core/src/iommu.rs"
click node_partition "https://github.com/amineux/aether/blob/main/core/src/partition.rs"
click node_sync "https://github.com/amineux/aether/blob/main/core/src/chipsync.rs"
click node_kv "https://github.com/amineux/aether/blob/main/core/src/kvfabric.rs"
click node_softsfi "https://github.com/amineux/aether/blob/main/core/src/softsfi.rs"
click node_injection "https://github.com/amineux/aether/blob/main/core/src/opinject.rs"
click node_accel "https://github.com/amineux/aether/blob/main/core/src/accel.rs"
click node_cp "https://github.com/amineux/aether/blob/main/drivers/src/fakecp.rs"
click node_softnpu "https://github.com/amineux/aether/blob/main/drivers/src/softnpu.rs"
click node_pjrt "https://github.com/amineux/aether/blob/main/host/aether-pjrt/src/lib.rs"
click node_mp "https://github.com/amineux/aether/blob/main/host/aether-mp-shim/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_loader,node_inituser,node_probe,node_app toneBlue
class node_syscall,node_world,node_memory,node_tasks toneAmber
class node_caps,node_fabriccore,node_arena,node_isolation,node_smmu toneMint
class node_partition,node_sync,node_kv,node_softsfi,node_injection,node_accel,node_cp,node_softnpu toneRose
class node_pjrt,node_mp toneIndigo
```

## Components

### Boot and execution

- [Kernel entry](https://github.com/amineux/aether/blob/main/kernel/src/main.rs): `kernel/src/main.rs`
- [ELF and bootfs](https://github.com/amineux/aether/blob/main/kernel/src/elfload.rs): `kernel/src/elfload.rs`
- [Init process](https://github.com/amineux/aether/blob/main/user/init/src/main.rs): `user/init/src/main.rs`
- [Probe process](https://github.com/amineux/aether/blob/main/user/probe/src/main.rs): `user/probe/src/main.rs`

### Kernel services

- [Syscall gate](https://github.com/amineux/aether/blob/main/kernel/src/syscall.rs): `kernel/src/syscall.rs`
- [Kernel objects](https://github.com/amineux/aether/blob/main/kernel/src/world.rs): `kernel/src/world.rs`
- [Address spaces](https://github.com/amineux/aether/blob/main/kernel/src/mm/paging.rs): `kernel/src/mm/paging.rs`
- [Threads and scheduler](https://github.com/amineux/aether/blob/main/kernel/src/task.rs): `kernel/src/task.rs`

### Fabric and isolation

- [Capabilities](https://github.com/amineux/aether/blob/main/core/src/caps.rs): `core/src/caps.rs`
- [Message fabric](https://github.com/amineux/aether/blob/main/core/src/fabric.rs): `core/src/fabric.rs`
- [Tensor arenas](https://github.com/amineux/aether/blob/main/core/src/arena.rs): `core/src/arena.rs`
- [Blast isolation](https://github.com/amineux/aether/blob/main/core/src/blast.rs): `core/src/blast.rs`
- [Soft SMMU](https://github.com/amineux/aether/blob/main/core/src/iommu.rs): `core/src/iommu.rs`

### Accelerator execution

- [Tile partitioning](https://github.com/amineux/aether/blob/main/core/src/partition.rs): `core/src/partition.rs`
- [Chiplet synchronization](https://github.com/amineux/aether/blob/main/core/src/chipsync.rs): `core/src/chipsync.rs`
- [KV fabric grants](https://github.com/amineux/aether/blob/main/core/src/kvfabric.rs): `core/src/kvfabric.rs`
- [SoftSFI sandbox](https://github.com/amineux/aether/blob/main/core/src/softsfi.rs): `core/src/softsfi.rs`
- [Resident op injection](https://github.com/amineux/aether/blob/main/core/src/opinject.rs): `core/src/opinject.rs`
- [Accelerator jobs](https://github.com/amineux/aether/blob/main/core/src/accel.rs): `core/src/accel.rs`
- [Command processor](https://github.com/amineux/aether/blob/main/drivers/src/fakecp.rs): `drivers/src/fakecp.rs`
- [SoftNPU driver](https://github.com/amineux/aether/blob/main/drivers/src/softnpu.rs): `drivers/src/softnpu.rs`

### Host and partner interfaces

- [PJRT interface](https://github.com/amineux/aether/blob/main/host/aether-pjrt/src/lib.rs): `host/aether-pjrt/src/lib.rs`
- [MP shim](https://github.com/amineux/aether/blob/main/host/aether-mp-shim/src/lib.rs): `host/aether-mp-shim/src/lib.rs`

### Other components

- **User workloads**

## Connections

- Kernel entry → ELF and bootfs: loads images (evidence: `kernel/src/main.rs`)
- Kernel entry → Threads and scheduler: spawns tasks (evidence: `kernel/src/main.rs`)
- ELF and bootfs → Init process: loads /init (evidence: `README.md`)
- ELF and bootfs → Probe process: loads probe
- Init process → Syscall gate: invokes syscalls (evidence: `README.md`)
- Probe process → Syscall gate: invokes syscalls (evidence: `README.md`)
- Syscall gate → Kernel objects: dispatches services (evidence: `kernel/src/syscall.rs`)
- Syscall gate → Address spaces: maps pages (evidence: `kernel/src/syscall.rs`)
- Syscall gate → Threads and scheduler: clones threads (evidence: `kernel/src/syscall.rs`)
- Kernel objects → Message fabric: sends messages (evidence: `kernel/src/world.rs`)
- Kernel objects → Capabilities: checks rights (evidence: `README.md`)
- Kernel objects → Tensor arenas: allocates arenas (evidence: `README.md`)
- Kernel objects → Accelerator jobs: submits jobs (evidence: `README.md`)
- Accelerator jobs → Tile partitioning: uses profiles (evidence: `core/src/accel.rs`)
- Command processor → Soft SMMU: resolves DMA
- Command processor → SoftNPU driver: executes commands
- Accelerator jobs → Chiplet synchronization: signals completion (evidence: `README.md`)
- KV fabric grants → Message fabric: grants KV (evidence: `README.md`)
- SoftSFI sandbox → Blast isolation: enforces sandbox (evidence: `README.md`)
- Resident op injection → Accelerator jobs: adds operations (evidence: `README.md`)
- PJRT interface → Command processor: submits commands (evidence: `README.md`)
- MP shim → PJRT interface: uses interface (evidence: `README.md`)
