# kkorel/pintos-kernel architecture

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

- Interactive diagram: https://gitdiagram.com/kkorel/pintos-kernel
- Repository: https://github.com/kkorel/pintos-kernel

## Overview

PintOS is a teaching kernel for 32-bit x86, implementing threads and user programs with a base file system. The principal workflow is a user program invoking a system call, which validates user memory and dispatches process or file operations; process execution loads an ELF executable and constructs its argument stack. The kernel also schedules threads, provides blocking synchronization and timer alarms, and accesses disk-backed file-system data. The README documents priority donation, MLFQS, and thirteen system calls. Some subsystem links are based on documentation because their implementation excerpts were not sampled.

Main entry points: [`src/userprog/syscall.c`](https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/syscall.c) (Syscall dispatch), [`src/userprog/process.c`](https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/process.c) (Process lifecycle), [`src/filesys/filesys.c`](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/filesys.c) (Filesystem operations), [`src/devices/block.c`](https://github.com/kkorel/pintos-kernel/blob/main/src/devices/block.c) (Block devices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Kernel core"]
  node_threads["Threads and schedulers<br/>[thread.c]"]
  node_sync["Synchronization<br/>[synch.c]"]
  node_interrupts["Interrupt handling<br/>[interrupt.c]"]
end

subgraph group_devices["Device I/O"]
  node_timer["Timer alarms<br/>[timer.c]"]
  node_block["Block devices<br/>[block.c]"]
  node_partition["Partition discovery<br/>[partition.c]"]
  node_ide["IDE disks<br/>[ide.c]"]
end

subgraph group_process["User processes"]
  node_process["Process lifecycle<br/>[process.c]"]
  node_exceptions["Exceptions<br/>[exception.c]"]
end

subgraph group_syscalls["System calls"]
  node_user_api["User syscall API<br/>[syscall.c]"]
  node_syscall_handler["Syscall dispatch<br/>[syscall.c]"]
end

subgraph group_filesystem["Base filesystem"]
  node_filesystem_api["Filesystem operations<br/>[filesys.c]"]
  node_file["File operations<br/>[file.c]"]
  node_directory["Directories<br/>[directory.c]"]
  node_inode["Inode storage<br/>[inode.c]"]
  node_free_map["Sector allocation<br/>[free-map.c]"]
end

node_user(("User program"))

node_user -->|"invokes"| node_user_api
node_user_api -->|"traps to"| node_syscall_handler
node_syscall_handler -->|"dispatches"| node_process
node_syscall_handler -->|"dispatches file calls"| node_filesystem_api
node_process -->|"creates threads"| node_threads
node_process -->|"loads executable"| node_filesystem_api
node_exceptions -->|"terminates on fault"| node_process
node_timer -->|"wakes sleepers"| node_threads
node_sync -->|"blocks and unblocks"| node_threads
node_syscall_handler -->|"registers trap"| node_interrupts
node_filesystem_api -->|"operates on files"| node_file
node_filesystem_api -->|"directory operations"| node_directory
node_file -->|"accesses inode"| node_inode
node_directory -->|"stores entries"| node_inode
node_free_map -->|"reads and writes"| node_block
node_inode -->|"reads and writes"| node_block
node_partition -->|"registers partitions"| node_block
node_ide -->|"registers disks"| node_block

click node_user_api "https://github.com/kkorel/pintos-kernel/blob/main/src/lib/user/syscall.c"
click node_syscall_handler "https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/syscall.c"
click node_process "https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/process.c"
click node_exceptions "https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/exception.c"
click node_threads "https://github.com/kkorel/pintos-kernel/blob/main/src/threads/thread.c"
click node_sync "https://github.com/kkorel/pintos-kernel/blob/main/src/threads/synch.c"
click node_timer "https://github.com/kkorel/pintos-kernel/blob/main/src/devices/timer.c"
click node_interrupts "https://github.com/kkorel/pintos-kernel/blob/main/src/threads/interrupt.c"
click node_filesystem_api "https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/filesys.c"
click node_file "https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/file.c"
click node_directory "https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/directory.c"
click node_inode "https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/inode.c"
click node_free_map "https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/free-map.c"
click node_block "https://github.com/kkorel/pintos-kernel/blob/main/src/devices/block.c"
click node_partition "https://github.com/kkorel/pintos-kernel/blob/main/src/devices/partition.c"
click node_ide "https://github.com/kkorel/pintos-kernel/blob/main/src/devices/ide.c"

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_threads,node_sync,node_interrupts,node_user toneBlue
class node_timer,node_block,node_partition,node_ide toneAmber
class node_process,node_exceptions toneMint
class node_user_api,node_syscall_handler toneRose
class node_filesystem_api,node_file,node_directory,node_inode,node_free_map toneIndigo
```

## Components

### Kernel core

- [Threads and schedulers](https://github.com/kkorel/pintos-kernel/blob/main/src/threads/thread.c): `src/threads/thread.c`
- [Synchronization](https://github.com/kkorel/pintos-kernel/blob/main/src/threads/synch.c): `src/threads/synch.c`
- [Interrupt handling](https://github.com/kkorel/pintos-kernel/blob/main/src/threads/interrupt.c): `src/threads/interrupt.c`

### Device I/O

- [Timer alarms](https://github.com/kkorel/pintos-kernel/blob/main/src/devices/timer.c): `src/devices/timer.c`
- [Block devices](https://github.com/kkorel/pintos-kernel/blob/main/src/devices/block.c): `src/devices/block.c`
- [Partition discovery](https://github.com/kkorel/pintos-kernel/blob/main/src/devices/partition.c): `src/devices/partition.c`
- [IDE disks](https://github.com/kkorel/pintos-kernel/blob/main/src/devices/ide.c): `src/devices/ide.c`

### User processes

- [Process lifecycle](https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/process.c): `src/userprog/process.c`
- [Exceptions](https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/exception.c): `src/userprog/exception.c`

### System calls

- [User syscall API](https://github.com/kkorel/pintos-kernel/blob/main/src/lib/user/syscall.c): `src/lib/user/syscall.c`
- [Syscall dispatch](https://github.com/kkorel/pintos-kernel/blob/main/src/userprog/syscall.c): `src/userprog/syscall.c`

### Base filesystem

- [Filesystem operations](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/filesys.c): `src/filesys/filesys.c`
- [File operations](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/file.c): `src/filesys/file.c`
- [Directories](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/directory.c): `src/filesys/directory.c`
- [Inode storage](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/inode.c): `src/filesys/inode.c`
- [Sector allocation](https://github.com/kkorel/pintos-kernel/blob/main/src/filesys/free-map.c): `src/filesys/free-map.c`

### Other components

- **User program**

## Connections

- User program → User syscall API: invokes
- User syscall API → Syscall dispatch: traps to
- Syscall dispatch → Process lifecycle: dispatches
- Syscall dispatch → Filesystem operations: dispatches file calls
- Process lifecycle → Threads and schedulers: creates threads
- Process lifecycle → Filesystem operations: loads executable
- Exceptions → Process lifecycle: terminates on fault
- Timer alarms → Threads and schedulers: wakes sleepers
- Synchronization → Threads and schedulers: blocks and unblocks
- Syscall dispatch → Interrupt handling: registers trap
- Filesystem operations → File operations: operates on files
- Filesystem operations → Directories: directory operations
- File operations → Inode storage: accesses inode
- Directories → Inode storage: stores entries
- Sector allocation → Block devices: reads and writes
- Inode storage → Block devices: reads and writes
- Partition discovery → Block devices: registers partitions
- IDE disks → Block devices: registers disks