# darkwood-byte/os architecture

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

- Interactive diagram: https://gitdiagram.com/darkwood-byte/os
- Repository: https://github.com/darkwood-byte/os

## Overview

This is a small RISC-V test OS kernel. Boot initializes memory and traps, creates an idle process, enables virtual memory, registers embedded user images, and starts init. User processes enter the kernel through traps and syscalls for process control, app lookup, console I/O, and shared socket access. Process creation loads images into user mappings; scheduling switches process contexts and address spaces. The memory excerpt is partial, so the graph shows only its evidenced allocator and mapping responsibilities; several syscall destinations are supported by the trap source, though their internals were not sampled.

Main entry points: [`trap_k.c`](https://github.com/darkwood-byte/os/blob/main/trap_k.c) (Syscall dispatch), [`pcb_k.c`](https://github.com/darkwood-byte/os/blob/main/pcb_k.c) (Process management), [`main.c`](https://github.com/darkwood-byte/os/blob/main/main.c) (Kernel startup), [`program_k.c`](https://github.com/darkwood-byte/os/blob/main/program_k.c) (Scheduler and switch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and Apps"]
  node_kernel["Kernel startup<br/>[main.c]"]
  node_app_catalog[("App catalog<br/>[app.c]")]
end

subgraph group_proc["Process Control"]
  node_processes["Process management<br/>[pcb_k.c]"]
  node_scheduler["Scheduler and switch<br/>[program_k.c]"]
end

subgraph group_mm["Memory and Mapping"]
  node_allocator_mapper["Allocator and mappings<br/>[memory.c]"]
end

subgraph group_kernel_api["Trap and Kernel Services"]
  node_trap_entry["Trap entry<br/>[trap_k.c]"]
  node_syscalls["Syscall dispatch<br/>[trap_k.c]"]
  node_sockets[("Shared sockets<br/>[sockets.c]")]
  node_console["Kernel console<br/>[print_k.c]"]
  node_string_utils["String utilities<br/>[str.c]"]
end

node_user_programs(("User programs"))
node_sbi["Supervisor interface<br/>[SBI.c]"]

node_kernel -->|"initializes memory"| node_allocator_mapper
node_kernel -->|"registers handler"| node_trap_entry
node_kernel -->|"creates idle process"| node_processes
node_kernel -->|"activates address space"| node_scheduler
node_kernel -->|"registers and starts"| node_app_catalog
node_app_catalog -->|"spawns image"| node_processes
node_user_programs -->|"invokes syscalls"| node_trap_entry
node_trap_entry -->|"dispatches trap"| node_syscalls
node_syscalls -->|"kills process"| node_processes
node_syscalls -->|"yields process"| node_scheduler
node_syscalls -->|"starts and looks up apps"| node_app_catalog
node_syscalls -->|"reads and writes"| node_sockets
node_syscalls -->|"handles console I/O"| node_console
node_syscalls -->|"compares app names"| node_string_utils
node_processes -->|"allocates and maps pages"| node_allocator_mapper
node_processes -->|"frees process pages"| node_allocator_mapper
node_scheduler -->|"selects process"| node_processes
node_scheduler -->|"switches context and TLB"| node_scheduler
node_console -.->|"uses platform interface"| node_sbi

click node_kernel "https://github.com/darkwood-byte/os/blob/main/main.c"
click node_app_catalog "https://github.com/darkwood-byte/os/blob/main/app.c"
click node_processes "https://github.com/darkwood-byte/os/blob/main/pcb_k.c"
click node_scheduler "https://github.com/darkwood-byte/os/blob/main/program_k.c"
click node_allocator_mapper "https://github.com/darkwood-byte/os/blob/main/memory.c"
click node_trap_entry "https://github.com/darkwood-byte/os/blob/main/trap_k.c"
click node_syscalls "https://github.com/darkwood-byte/os/blob/main/trap_k.c"
click node_sockets "https://github.com/darkwood-byte/os/blob/main/sockets.c"
click node_console "https://github.com/darkwood-byte/os/blob/main/print_k.c"
click node_string_utils "https://github.com/darkwood-byte/os/blob/main/str.c"
click node_sbi "https://github.com/darkwood-byte/os/blob/main/SBI.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,node_app_catalog,node_user_programs toneBlue
class node_processes,node_scheduler toneAmber
class node_allocator_mapper toneMint
class node_trap_entry,node_syscalls,node_sockets,node_console,node_string_utils toneRose
class node_sbi toneTeal
```

## Components

### Boot and Apps

- [Kernel startup](https://github.com/darkwood-byte/os/blob/main/main.c): `main.c`
- [App catalog](https://github.com/darkwood-byte/os/blob/main/app.c): `app.c`

### Process Control

- [Process management](https://github.com/darkwood-byte/os/blob/main/pcb_k.c): `pcb_k.c`
- [Scheduler and switch](https://github.com/darkwood-byte/os/blob/main/program_k.c): `program_k.c`

### Memory and Mapping

- [Allocator and mappings](https://github.com/darkwood-byte/os/blob/main/memory.c): `memory.c`

### Trap and Kernel Services

- [Trap entry](https://github.com/darkwood-byte/os/blob/main/trap_k.c): `trap_k.c`
- [Syscall dispatch](https://github.com/darkwood-byte/os/blob/main/trap_k.c): `trap_k.c`
- [Shared sockets](https://github.com/darkwood-byte/os/blob/main/sockets.c): `sockets.c`
- [Kernel console](https://github.com/darkwood-byte/os/blob/main/print_k.c): `print_k.c`
- [String utilities](https://github.com/darkwood-byte/os/blob/main/str.c): `str.c`

### Other components

- **User programs**
- [Supervisor interface](https://github.com/darkwood-byte/os/blob/main/SBI.c): `SBI.c`

## Connections

- Kernel startup → Allocator and mappings: initializes memory
- Kernel startup → Trap entry: registers handler
- Kernel startup → Process management: creates idle process
- Kernel startup → Scheduler and switch: activates address space
- Kernel startup → App catalog: registers and starts
- App catalog → Process management: spawns image
- User programs → Trap entry: invokes syscalls
- Trap entry → Syscall dispatch: dispatches trap
- Syscall dispatch → Process management: kills process
- Syscall dispatch → Scheduler and switch: yields process
- Syscall dispatch → App catalog: starts and looks up apps
- Syscall dispatch → Shared sockets: reads and writes
- Syscall dispatch → Kernel console: handles console I/O
- Syscall dispatch → String utilities: compares app names
- Process management → Allocator and mappings: allocates and maps pages
- Process management → Allocator and mappings: frees process pages
- Scheduler and switch → Process management: selects process
- Scheduler and switch → Scheduler and switch: switches context and TLB
- Kernel console → Supervisor interface: uses platform interface