# devking-kunal/cos architecture

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

- Interactive diagram: https://gitdiagram.com/devking-kunal/cos
- Repository: https://github.com/devking-kunal/cos

## Overview

cOS is an educational RISC-V operating system whose main workflow boots the kernel, starts the first user process, and runs user programs through system calls into kernel services. Process management and virtual memory support execution; filesystem calls resolve paths and transfer data through the buffer cache to the VirtIO disk. The README also documents process telemetry (`procinfo`) and console I/O. The tree omits assembly entry/trap stubs, so those implementation details are not mapped; the documented trap-to-dispatch relationship is shown.

Main entry points: [`kernel/main.c`](https://github.com/devking-kunal/cos/blob/main/kernel/main.c) (Kernel Bring-up), [`kernel/trap.c`](https://github.com/devking-kunal/cos/blob/main/kernel/trap.c) (Trap Handling), [`kernel/syscall.c`](https://github.com/devking-kunal/cos/blob/main/kernel/syscall.c) (Syscall Dispatch), [`kernel/sysproc.c`](https://github.com/devking-kunal/cos/blob/main/kernel/sysproc.c) (Process Syscalls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and I/O"]
  node_kernel_main["Kernel Bring-up<br/>[main.c]"]
  node_trap["Trap Handling<br/>[trap.c]"]
  node_console["Console Input<br/>[console.c]"]
  node_uart["UART Driver<br/>[uart.c]"]
  node_plic["Interrupt Controller<br/>[plic.c]"]
end

subgraph group_userspace["User Programs"]
  node_init["Init Process<br/>[init.c]"]
  node_shell["Command Shell<br/>[sh.c]"]
  node_user_api["User API<br/>[user.h]"]
end

subgraph group_execution["Execution Services"]
  node_syscall["Syscall Dispatch<br/>[syscall.c]"]
  node_sysfile["File Syscalls<br/>[sysfile.c]"]
  node_sysproc["Process Syscalls<br/>[sysproc.c]"]
  node_process["Process Scheduler<br/>[proc.c]"]
end

subgraph group_memory["Memory Management"]
  node_vm["Virtual Memory<br/>[vm.c]"]
  node_allocator["Page Allocator<br/>[kalloc.c]"]
end

subgraph group_storage["Storage"]
  node_files["Open File Layer<br/>[file.c]"]
  node_filesystem["Filesystem<br/>[fs.c]"]
  node_buffers["Block Cache<br/>[bio.c]"]
  node_disk["VirtIO Disk<br/>[virtio_disk.c]"]
end

node_platform(("RISC-V Platform"))
node_user_actor(("User"))

node_platform -->|"starts kernel"| node_kernel_main
node_kernel_main -->|"initializes processes"| node_process
node_kernel_main -->|"initializes paging"| node_vm
node_kernel_main -->|"sets trap vectors"| node_trap
node_kernel_main -->|"configures interrupts"| node_plic
node_kernel_main -->|"initializes cache"| node_buffers
node_kernel_main -->|"initializes inodes"| node_filesystem
node_kernel_main -->|"initializes device"| node_disk
node_process -->|"executes /init"| node_init
node_user_actor -->|"enters commands"| node_shell
node_init -->|"starts shell"| node_shell
node_shell -->|"invokes user services"| node_user_api
node_user_api -->|"requests kernel service"| node_trap
node_trap -->|"dispatches syscall"| node_syscall
node_syscall -->|"dispatches file calls"| node_sysfile
node_syscall -->|"dispatches process calls"| node_sysproc
node_sysproc -->|"queries process state"| node_process
node_sysproc -->|"measures resident pages"| node_vm
node_sysfile -->|"operates on descriptors"| node_files
node_files -->|"accesses inodes"| node_filesystem
node_filesystem -->|"reads and writes blocks"| node_buffers
node_buffers -->|"requests disk I/O"| node_disk
node_vm -->|"allocates pages"| node_allocator
node_console -->|"reads and writes"| node_uart
node_plic -->|"signals interrupts"| node_trap

click node_kernel_main "https://github.com/devking-kunal/cos/blob/main/kernel/main.c"
click node_trap "https://github.com/devking-kunal/cos/blob/main/kernel/trap.c"
click node_console "https://github.com/devking-kunal/cos/blob/main/kernel/console.c"
click node_uart "https://github.com/devking-kunal/cos/blob/main/kernel/uart.c"
click node_plic "https://github.com/devking-kunal/cos/blob/main/kernel/plic.c"
click node_init "https://github.com/devking-kunal/cos/blob/main/user/init.c"
click node_shell "https://github.com/devking-kunal/cos/blob/main/user/sh.c"
click node_user_api "https://github.com/devking-kunal/cos/blob/main/user/user.h"
click node_syscall "https://github.com/devking-kunal/cos/blob/main/kernel/syscall.c"
click node_sysfile "https://github.com/devking-kunal/cos/blob/main/kernel/sysfile.c"
click node_sysproc "https://github.com/devking-kunal/cos/blob/main/kernel/sysproc.c"
click node_process "https://github.com/devking-kunal/cos/blob/main/kernel/proc.c"
click node_files "https://github.com/devking-kunal/cos/blob/main/kernel/file.c"
click node_filesystem "https://github.com/devking-kunal/cos/blob/main/kernel/fs.c"
click node_buffers "https://github.com/devking-kunal/cos/blob/main/kernel/bio.c"
click node_disk "https://github.com/devking-kunal/cos/blob/main/kernel/virtio_disk.c"
click node_vm "https://github.com/devking-kunal/cos/blob/main/kernel/vm.c"
click node_allocator "https://github.com/devking-kunal/cos/blob/main/kernel/kalloc.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_kernel_main,node_trap,node_console,node_uart,node_plic,node_user_actor toneBlue
class node_init,node_shell,node_user_api toneAmber
class node_syscall,node_sysfile,node_sysproc,node_process toneMint
class node_vm,node_allocator toneRose
class node_files,node_filesystem,node_buffers,node_disk,node_platform toneIndigo
```

## Components

### Startup and I/O

- [Kernel Bring-up](https://github.com/devking-kunal/cos/blob/main/kernel/main.c): `kernel/main.c`
- [Trap Handling](https://github.com/devking-kunal/cos/blob/main/kernel/trap.c): `kernel/trap.c`
- [Console Input](https://github.com/devking-kunal/cos/blob/main/kernel/console.c): `kernel/console.c`
- [UART Driver](https://github.com/devking-kunal/cos/blob/main/kernel/uart.c): `kernel/uart.c`
- [Interrupt Controller](https://github.com/devking-kunal/cos/blob/main/kernel/plic.c): `kernel/plic.c`

### User Programs

- [Init Process](https://github.com/devking-kunal/cos/blob/main/user/init.c): `user/init.c`
- [Command Shell](https://github.com/devking-kunal/cos/blob/main/user/sh.c): `user/sh.c`
- [User API](https://github.com/devking-kunal/cos/blob/main/user/user.h): `user/user.h`

### Execution Services

- [Syscall Dispatch](https://github.com/devking-kunal/cos/blob/main/kernel/syscall.c): `kernel/syscall.c`
- [File Syscalls](https://github.com/devking-kunal/cos/blob/main/kernel/sysfile.c): `kernel/sysfile.c`
- [Process Syscalls](https://github.com/devking-kunal/cos/blob/main/kernel/sysproc.c): `kernel/sysproc.c`
- [Process Scheduler](https://github.com/devking-kunal/cos/blob/main/kernel/proc.c): `kernel/proc.c`

### Memory Management

- [Virtual Memory](https://github.com/devking-kunal/cos/blob/main/kernel/vm.c): `kernel/vm.c`
- [Page Allocator](https://github.com/devking-kunal/cos/blob/main/kernel/kalloc.c): `kernel/kalloc.c`

### Storage

- [Open File Layer](https://github.com/devking-kunal/cos/blob/main/kernel/file.c): `kernel/file.c`
- [Filesystem](https://github.com/devking-kunal/cos/blob/main/kernel/fs.c): `kernel/fs.c`
- [Block Cache](https://github.com/devking-kunal/cos/blob/main/kernel/bio.c): `kernel/bio.c`
- [VirtIO Disk](https://github.com/devking-kunal/cos/blob/main/kernel/virtio_disk.c): `kernel/virtio_disk.c`

### Other components

- **RISC-V Platform**
- **User**

## Connections

- RISC-V Platform → Kernel Bring-up: starts kernel
- Kernel Bring-up → Process Scheduler: initializes processes
- Kernel Bring-up → Virtual Memory: initializes paging
- Kernel Bring-up → Trap Handling: sets trap vectors
- Kernel Bring-up → Interrupt Controller: configures interrupts
- Kernel Bring-up → Block Cache: initializes cache
- Kernel Bring-up → Filesystem: initializes inodes
- Kernel Bring-up → VirtIO Disk: initializes device
- Process Scheduler → Init Process: executes /init
- User → Command Shell: enters commands
- Init Process → Command Shell: starts shell
- Command Shell → User API: invokes user services
- User API → Trap Handling: requests kernel service
- Trap Handling → Syscall Dispatch: dispatches syscall
- Syscall Dispatch → File Syscalls: dispatches file calls
- Syscall Dispatch → Process Syscalls: dispatches process calls
- Process Syscalls → Process Scheduler: queries process state
- Process Syscalls → Virtual Memory: measures resident pages
- File Syscalls → Open File Layer: operates on descriptors
- Open File Layer → Filesystem: accesses inodes
- Filesystem → Block Cache: reads and writes blocks
- Block Cache → VirtIO Disk: requests disk I/O
- Virtual Memory → Page Allocator: allocates pages
- Console Input → UART Driver: reads and writes
- Interrupt Controller → Trap Handling: signals interrupts