# manvesh2011/rust-os-starter architecture

> Architecture diagram of the GitHub repository manvesh2011/rust-os-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manvesh2011/rust-os-starter
- Repository: https://github.com/manvesh2011/rust-os-starter

## Overview

rust-os-starter is a minimal no_std AArch64 kernel for QEMU’s virt machine. Its boot path initializes interrupt handling and memory translation, probes the optional VirtIO block device, starts kernel threads, then relies on timer-driven preemption; UART reports output and receives input. The runtime also exposes an SVC interface for user processes, memory allocation, and IPC, with user mappings checked by usercopy. The README documents additional capability control and hardware support; sampled excerpts do not show all their wiring, so uncertain links are omitted.

Main entry points: [`kernel/src/main.rs`](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/main.rs) (Kernel entry), [`kernel/src/syscall.rs`](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/syscall.rs) (SVC dispatcher), [`kernel/src/process.rs`](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/process.rs) (Process manager), [`kernel/src/scheduler.rs`](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/scheduler.rs) (Thread scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and platform"]
  node_kernel_entry["Kernel entry<br/>[main.rs]"]
  node_bootinfo["Boot information<br/>[bootinfo.rs]"]
  node_memmap["Platform map<br/>[memmap.rs]"]
  node_exceptions["Exception vectors<br/>[exceptions.rs]"]
  node_gic["GICv2 controller<br/>[gic.rs]"]
  node_timer["Generic timer<br/>[timer.rs]"]
end

subgraph group_execution["Execution and syscalls"]
  node_scheduler["Thread scheduler<br/>[scheduler.rs]"]
  node_process["Process manager<br/>[process.rs]"]
  node_syscall["SVC dispatcher<br/>[syscall.rs]"]
  node_ipc["IPC queue<br/>[ipc.rs]"]
  node_capability["Capability access<br/>[capability.rs]"]
end

subgraph group_memory["Memory and protection"]
  node_mmu["MMU and page tables<br/>[mmu.rs]"]
  node_memory[("Page allocator<br/>[memory.rs]")]
  node_heap["Bump heap<br/>[heap.rs]"]
  node_usercopy["User-pointer checks<br/>[usercopy.rs]"]
  node_sync["Spin mutex<br/>[sync.rs]"]
end

subgraph group_io["Devices and communication"]
  node_uart["PL011 UART<br/>[uart.rs]"]
  node_virtio["VirtIO block driver<br/>[virtio_blk.rs]"]
end

node_qemu(("QEMU virt"))

node_qemu -->|"loads kernel"| node_kernel_entry
node_kernel_entry -->|"installs vectors"| node_exceptions
node_kernel_entry -->|"initializes"| node_gic
node_kernel_entry -->|"enables mapping"| node_mmu
node_kernel_entry -->|"probes device"| node_virtio
node_kernel_entry -->|"spawns threads"| node_scheduler
node_kernel_entry -->|"prints boot status"| node_uart
node_exceptions -->|"dispatches SVC"| node_syscall
node_exceptions -->|"schedules IRQ"| node_scheduler
node_exceptions -->|"acknowledges IRQ"| node_gic
node_gic -->|"routes timer IRQ"| node_timer
node_gic -->|"routes RX IRQ"| node_uart
node_scheduler -->|"tracks current PID"| node_process
node_process -->|"creates thread"| node_scheduler
node_process -->|"allocates process pages"| node_memory
node_process -->|"switches user table"| node_mmu
node_syscall -->|"yields thread"| node_scheduler
node_syscall -->|"allocates or frees"| node_memory
node_syscall -->|"sends or receives"| node_ipc
node_syscall -->|"writes byte"| node_uart
node_usercopy -->|"gets user table"| node_process
node_usercopy -->|"checks mappings"| node_mmu
node_qemu -.->|"provides block device"| node_virtio

click node_kernel_entry "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/main.rs"
click node_bootinfo "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/bootinfo.rs"
click node_memmap "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/memmap.rs"
click node_exceptions "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/exceptions.rs"
click node_gic "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/gic.rs"
click node_timer "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/timer.rs"
click node_scheduler "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/scheduler.rs"
click node_process "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/process.rs"
click node_syscall "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/syscall.rs"
click node_ipc "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/ipc.rs"
click node_capability "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/capability.rs"
click node_mmu "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/mmu.rs"
click node_memory "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/memory.rs"
click node_heap "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/heap.rs"
click node_usercopy "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/usercopy.rs"
click node_sync "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/sync.rs"
click node_uart "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/uart.rs"
click node_virtio "https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/virtio_blk.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_kernel_entry,node_bootinfo,node_memmap,node_exceptions,node_gic,node_timer toneBlue
class node_scheduler,node_process,node_syscall,node_ipc,node_capability toneAmber
class node_mmu,node_memory,node_heap,node_usercopy,node_sync toneMint
class node_uart,node_virtio toneRose
class node_qemu toneIndigo
```

## Components

### Boot and platform

- [Kernel entry](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/main.rs): `kernel/src/main.rs`
- [Boot information](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/bootinfo.rs): `kernel/src/bootinfo.rs`
- [Platform map](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/memmap.rs): `kernel/src/memmap.rs`
- [Exception vectors](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/exceptions.rs): `kernel/src/exceptions.rs`
- [GICv2 controller](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/gic.rs): `kernel/src/gic.rs`
- [Generic timer](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/timer.rs): `kernel/src/timer.rs`

### Execution and syscalls

- [Thread scheduler](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/scheduler.rs): `kernel/src/scheduler.rs`
- [Process manager](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/process.rs): `kernel/src/process.rs`
- [SVC dispatcher](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/syscall.rs): `kernel/src/syscall.rs`
- [IPC queue](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/ipc.rs): `kernel/src/ipc.rs`
- [Capability access](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/capability.rs): `kernel/src/capability.rs`

### Memory and protection

- [MMU and page tables](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/mmu.rs): `kernel/src/mmu.rs`
- [Page allocator](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/memory.rs): `kernel/src/memory.rs`
- [Bump heap](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/heap.rs): `kernel/src/heap.rs`
- [User-pointer checks](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/usercopy.rs): `kernel/src/usercopy.rs`
- [Spin mutex](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/sync.rs): `kernel/src/sync.rs`

### Devices and communication

- [PL011 UART](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/uart.rs): `kernel/src/uart.rs`
- [VirtIO block driver](https://github.com/manvesh2011/rust-os-starter/blob/main/kernel/src/virtio_blk.rs): `kernel/src/virtio_blk.rs`

### Other components

- **QEMU virt**

## Connections

- QEMU virt → Kernel entry: loads kernel
- Kernel entry → Exception vectors: installs vectors
- Kernel entry → GICv2 controller: initializes
- Kernel entry → MMU and page tables: enables mapping
- Kernel entry → VirtIO block driver: probes device
- Kernel entry → Thread scheduler: spawns threads
- Kernel entry → PL011 UART: prints boot status
- Exception vectors → SVC dispatcher: dispatches SVC
- Exception vectors → Thread scheduler: schedules IRQ
- Exception vectors → GICv2 controller: acknowledges IRQ
- GICv2 controller → Generic timer: routes timer IRQ
- GICv2 controller → PL011 UART: routes RX IRQ
- Thread scheduler → Process manager: tracks current PID
- Process manager → Thread scheduler: creates thread
- Process manager → Page allocator: allocates process pages
- Process manager → MMU and page tables: switches user table
- SVC dispatcher → Thread scheduler: yields thread
- SVC dispatcher → Page allocator: allocates or frees
- SVC dispatcher → IPC queue: sends or receives
- SVC dispatcher → PL011 UART: writes byte
- User-pointer checks → Process manager: gets user table
- User-pointer checks → MMU and page tables: checks mappings
- QEMU virt → VirtIO block driver: provides block device