# casys-kaist/keos architecture

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

- Interactive diagram: https://gitdiagram.com/casys-kaist/keos
- Repository: https://github.com/casys-kaist/keos

## Overview

OS-projects is an educational operating-systems and virtualization repository: learners implement KeOS kernel features across five sequential projects, then KeV virtualization features across its project sequence. The runtime layer is KeOS, with KeV using it as its host; project directories provide the implementation stages. The README establishes the curriculum and progression, while sampled bootstrap code shows VMX startup and filesystem registration. Individual project internals are not sampled, so their detailed runtime wiring is intentionally omitted.

Main entry points: [`keos/src/lib.rs`](https://github.com/casys-kaist/keos/blob/main/keos/src/lib.rs) (KeOS kernel), [`kev/src/lib.rs`](https://github.com/casys-kaist/keos/blob/main/kev/src/lib.rs) (KeV runtime), [`keos-projects/keos-project5/src/ffs/mod.rs`](https://github.com/casys-kaist/keos/blob/main/keos-projects/keos-project5/src/ffs/mod.rs) (Fast filesystem), [`keos-projects/keos-project1/src`](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project1/src) (System calls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_keos["KeOS kernel"]
  node_kernel["KeOS kernel<br/>[lib.rs]"]
end

subgraph group_keos_projects["KeOS projects"]
  node_syscall_stage["System calls"]
  node_memory_stage["Memory management"]
  node_advanced_memory["Advanced memory"]
  node_process_stage["Process management"]
  node_fs_stage["Filesystem project"]
  node_libc["User C library"]
end

subgraph group_kev_core["KeV hypervisor"]
  node_hypervisor["KeV runtime<br/>[lib.rs]"]
  node_vm_control["VM control<br/>[vm_control.rs]"]
  node_vmexit["VM exits<br/>[vmexits.rs]"]
end

subgraph group_kev_projects["KeV projects"]
  node_kev_base["KeOS foundations<br/>[lib.rs]"]
  node_vmx_stage["VMCS and exits"]
  node_hardware_stage["Hardware virtualization"]
  node_io_stage["Interrupt and I/O"]
  node_final_stage["Final project"]
end

subgraph group_filesystem["Filesystem"]
  node_simple_fs["SimpleFS adapter<br/>[lib.rs]"]
  node_fast_fs["Fast filesystem<br/>[mod.rs]"]
  node_page_cache["Page cache<br/>[mod.rs]"]
end

node_learner(("Learner"))
node_disk[("Disk")]
node_cpu{{"x86 hardware"}}

node_learner -->|"implements first"| node_syscall_stage
node_syscall_stage -->|"builds on"| node_memory_stage
node_memory_stage -->|"builds on"| node_advanced_memory
node_advanced_memory -->|"builds on"| node_process_stage
node_process_stage -->|"builds on"| node_fs_stage
node_kernel -->|"hosts project"| node_syscall_stage
node_kernel -->|"hosts project"| node_memory_stage
node_kernel -->|"hosts project"| node_advanced_memory
node_kernel -->|"hosts project"| node_process_stage
node_kernel -->|"hosts project"| node_fs_stage
node_libc -->|"invokes syscalls"| node_kernel
node_fs_stage -->|"implements"| node_fast_fs
node_fast_fs -->|"wrapped by"| node_page_cache
node_fast_fs -->|"reads and writes"| node_disk
node_simple_fs -->|"loads from"| node_disk
node_learner -->|"starts with"| node_kev_base
node_kev_base -->|"builds on"| node_vmx_stage
node_vmx_stage -->|"builds on"| node_hardware_stage
node_hardware_stage -->|"builds on"| node_io_stage
node_io_stage -->|"extends project"| node_final_stage
node_kernel -->|"provides host"| node_hypervisor
node_hypervisor -->|"controls VMs"| node_vm_control
node_vm_control -->|"handles exits"| node_vmexit
node_hypervisor -->|"initializes VMX"| node_cpu

click node_kernel "https://github.com/casys-kaist/keos/blob/main/keos/src/lib.rs"
click node_syscall_stage "https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project1/src"
click node_memory_stage "https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project2/src"
click node_advanced_memory "https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project3/src"
click node_process_stage "https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project4/src"
click node_fs_stage "https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project5/src"
click node_libc "https://github.com/casys-kaist/keos/tree/main/keos-projects/kelibc"
click node_simple_fs "https://github.com/casys-kaist/keos/blob/main/fs/simple_fs/src/lib.rs"
click node_fast_fs "https://github.com/casys-kaist/keos/blob/main/keos-projects/keos-project5/src/ffs/mod.rs"
click node_page_cache "https://github.com/casys-kaist/keos/blob/main/keos-projects/keos-project5/src/page_cache/mod.rs"
click node_hypervisor "https://github.com/casys-kaist/keos/blob/main/kev/src/lib.rs"
click node_vm_control "https://github.com/casys-kaist/keos/blob/main/kev/src/vm_control.rs"
click node_vmexit "https://github.com/casys-kaist/keos/blob/main/kev/src/vmexits.rs"
click node_kev_base "https://github.com/casys-kaist/keos/blob/main/kev-projects/kev-project0/src/lib.rs"
click node_vmx_stage "https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project1/src"
click node_hardware_stage "https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project2/src"
click node_io_stage "https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project3/src"
click node_final_stage "https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project4"

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 toneBlue
class node_syscall_stage,node_memory_stage,node_advanced_memory,node_process_stage,node_fs_stage,node_libc,node_disk toneAmber
class node_hypervisor,node_vm_control,node_vmexit toneMint
class node_kev_base,node_vmx_stage,node_hardware_stage,node_io_stage,node_final_stage toneRose
class node_simple_fs,node_fast_fs,node_page_cache,node_learner,node_cpu toneIndigo
```

## Components

### KeOS kernel

- [KeOS kernel](https://github.com/casys-kaist/keos/blob/main/keos/src/lib.rs): `keos/src/lib.rs`

### KeOS projects

- [System calls](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project1/src): `keos-projects/keos-project1/src`
- [Memory management](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project2/src): `keos-projects/keos-project2/src`
- [Advanced memory](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project3/src): `keos-projects/keos-project3/src`
- [Process management](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project4/src): `keos-projects/keos-project4/src`
- [Filesystem project](https://github.com/casys-kaist/keos/tree/main/keos-projects/keos-project5/src): `keos-projects/keos-project5/src`
- [User C library](https://github.com/casys-kaist/keos/tree/main/keos-projects/kelibc): `keos-projects/kelibc`

### KeV hypervisor

- [KeV runtime](https://github.com/casys-kaist/keos/blob/main/kev/src/lib.rs): `kev/src/lib.rs`
- [VM control](https://github.com/casys-kaist/keos/blob/main/kev/src/vm_control.rs): `kev/src/vm_control.rs`
- [VM exits](https://github.com/casys-kaist/keos/blob/main/kev/src/vmexits.rs): `kev/src/vmexits.rs`

### KeV projects

- [KeOS foundations](https://github.com/casys-kaist/keos/blob/main/kev-projects/kev-project0/src/lib.rs): `kev-projects/kev-project0/src/lib.rs`
- [VMCS and exits](https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project1/src): `kev-projects/kev-project1/src`
- [Hardware virtualization](https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project2/src): `kev-projects/kev-project2/src`
- [Interrupt and I/O](https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project3/src): `kev-projects/kev-project3/src`
- [Final project](https://github.com/casys-kaist/keos/tree/main/kev-projects/kev-project4): `kev-projects/kev-project4`

### Filesystem

- [SimpleFS adapter](https://github.com/casys-kaist/keos/blob/main/fs/simple_fs/src/lib.rs): `fs/simple_fs/src/lib.rs`
- [Fast filesystem](https://github.com/casys-kaist/keos/blob/main/keos-projects/keos-project5/src/ffs/mod.rs): `keos-projects/keos-project5/src/ffs/mod.rs`
- [Page cache](https://github.com/casys-kaist/keos/blob/main/keos-projects/keos-project5/src/page_cache/mod.rs): `keos-projects/keos-project5/src/page_cache/mod.rs`

### Other components

- **Learner**
- **Disk**
- **x86 hardware**

## Connections

- Learner → System calls: implements first
- System calls → Memory management: builds on
- Memory management → Advanced memory: builds on
- Advanced memory → Process management: builds on
- Process management → Filesystem project: builds on
- KeOS kernel → System calls: hosts project
- KeOS kernel → Memory management: hosts project
- KeOS kernel → Advanced memory: hosts project
- KeOS kernel → Process management: hosts project
- KeOS kernel → Filesystem project: hosts project
- User C library → KeOS kernel: invokes syscalls
- Filesystem project → Fast filesystem: implements
- Fast filesystem → Page cache: wrapped by
- Fast filesystem → Disk: reads and writes
- SimpleFS adapter → Disk: loads from
- Learner → KeOS foundations: starts with
- KeOS foundations → VMCS and exits: builds on
- VMCS and exits → Hardware virtualization: builds on
- Hardware virtualization → Interrupt and I/O: builds on
- Interrupt and I/O → Final project: extends project
- KeOS kernel → KeV runtime: provides host
- KeV runtime → VM control: controls VMs
- VM control → VM exits: handles exits
- KeV runtime → x86 hardware: initializes VMX