# bouezleonardo/polvoss-kernel architecture

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

- Interactive diagram: https://gitdiagram.com/bouezleonardo/polvoss-kernel
- Repository: https://github.com/bouezleonardo/polvoss-kernel

## Overview

This is a small RISC-V kernel implementing boot, virtual memory, process execution and scheduling, traps/syscalls, and console/device I/O. The principal workflow initializes machine state and memory, starts an initial ELF process, schedules it, then handles user traps and system calls before returning to execution. The graph preserves the major runtime stages and supporting synchronization and architecture layers. README content is absent; some subsystem links are based on source-index references rather than inspected call sites, so those are marked unverified.

Main entry points: [`src/proc/processing.rs`](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/processing.rs) (Process management), [`src/boot/start.rs`](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/boot/start.rs) (Boot initialization), [`src/memory/virtual_memory.rs`](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/virtual_memory.rs) (Virtual memory), [`src/trap/trap_handlers.rs`](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/trap_handlers.rs) (Trap handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot"]
  node_kernel["Kernel entry<br/>[main.rs]"]
  node_boot_init["Boot initialization<br/>[start.rs]"]
  node_boot_config["Machine setup<br/>[hard_config.rs]"]
  node_constants["System constants<br/>[constants.rs]"]
end

subgraph group_memory["Memory"]
  node_frame_alloc["Frame allocator<br/>[frame_alloc.rs]"]
  node_memory_layout["Physical layout<br/>[memory_layout.rs]"]
  node_virtual_memory["Virtual memory<br/>[virtual_memory.rs]"]
  node_memory_types["Address and page tables<br/>[memory_types.rs]"]
end

subgraph group_process["Processes"]
  node_elf["ELF loader<br/>[elf.rs]"]
  node_loader["Process loader<br/>[loader.rs]"]
  node_process_state["Process state<br/>[control_types.rs]"]
  node_processing["Process management<br/>[processing.rs]"]
  node_scheduler["Scheduler<br/>[scheduler.rs]"]
  node_round_robin["Round-robin policy<br/>[round_robin.rs]"]
  node_sync["Process synchronization<br/>[sync.rs]"]
  node_spin["Spin mutex<br/>[spin.rs]"]
end

subgraph group_trap["Traps and syscalls"]
  node_trap_handlers["Trap handling<br/>[trap_handlers.rs]"]
  node_uservec["User trap vector<br/>[uservec.rs]"]
  node_syscall_handler["Syscall dispatch<br/>[syscall_handler.rs]"]
  node_syscall_proc["Process syscalls<br/>[syscall_proc.rs]"]
  node_syscall_file["File syscalls<br/>[syscall_file.rs]"]
  node_plic["Interrupt controller<br/>[plic.rs]"]
end

subgraph group_platform["Platform I/O and RISC-V"]
  node_console["Console<br/>[console.rs]"]
  node_uart["UART<br/>[uart.rs]"]
  node_monitor["Display monitor<br/>[monitor.rs]"]
  node_supervisor["Supervisor controls<br/>[supervisor_mode.rs]"]
end

node_user(("User process"))
node_hardware(("RISC-V hardware"))

node_kernel -.->|"starts"| node_boot_init
node_boot_init -.->|"configures"| node_boot_config
node_boot_init -->|"initializes"| node_frame_alloc
node_boot_init -->|"initializes"| node_virtual_memory
node_boot_init -->|"starts"| node_processing
node_boot_init -->|"starts"| node_scheduler
node_boot_init -->|"installs"| node_trap_handlers
node_boot_config -.->|"configures"| node_supervisor
node_frame_alloc -.->|"bounds allocation"| node_memory_layout
node_frame_alloc -.->|"locks allocator"| node_spin
node_virtual_memory -.->|"allocates frames"| node_frame_alloc
node_virtual_memory -.->|"maps layout"| node_memory_layout
node_virtual_memory -.->|"uses page tables"| node_memory_types
node_virtual_memory -.->|"updates address space"| node_process_state
node_loader -.->|"loads image"| node_elf
node_loader -.->|"maps process"| node_virtual_memory
node_loader -.->|"sets process state"| node_process_state
node_processing -.->|"loads init process"| node_loader
node_processing -.->|"creates process image"| node_virtual_memory
node_processing -.->|"manages PCB"| node_process_state
node_scheduler -.->|"switches processes"| node_processing
node_scheduler -.->|"selects process"| node_round_robin
node_processing -.->|"uses locks"| node_spin
node_sync -->|"schedules waiters"| node_processing
node_sync -.->|"protects queues"| node_spin
node_user -.->|"traps into"| node_uservec
node_uservec -.->|"dispatches trap"| node_trap_handlers
node_trap_handlers -->|"dispatches syscall"| node_syscall_handler
node_syscall_handler -.->|"dispatches process calls"| node_syscall_proc
node_syscall_handler -.->|"dispatches file calls"| node_syscall_file
node_syscall_proc -.->|"operates on processes"| node_processing
node_trap_handlers -.->|"handles device interrupts"| node_plic
node_trap_handlers -.->|"reads trap state"| node_supervisor
node_boot_init -.->|"initializes"| node_console
node_console -->|"writes display"| node_monitor
node_console -.->|"uses serial I/O"| node_uart
node_console -.->|"copies user data"| node_processing
node_plic -.->|"signals device event"| node_processing
node_hardware -.->|"raises interrupts"| node_plic
node_hardware -.->|"provides device I/O"| node_uart

click node_kernel "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/main.rs"
click node_boot_init "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/boot/start.rs"
click node_boot_config "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/boot/hard_config.rs"
click node_constants "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/config/constants.rs"
click node_frame_alloc "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/frame_alloc.rs"
click node_memory_layout "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/memory_layout.rs"
click node_virtual_memory "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/virtual_memory.rs"
click node_memory_types "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/riscv/memory_types.rs"
click node_elf "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/file/elf.rs"
click node_loader "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/loader.rs"
click node_process_state "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/control_types.rs"
click node_processing "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/processing.rs"
click node_scheduler "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/scheduler.rs"
click node_round_robin "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/round_robin.rs"
click node_sync "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/sync.rs"
click node_spin "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/spin.rs"
click node_trap_handlers "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/trap_handlers.rs"
click node_uservec "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/uservec.rs"
click node_syscall_handler "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_handler.rs"
click node_syscall_proc "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_proc.rs"
click node_syscall_file "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_file.rs"
click node_plic "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/plic.rs"
click node_console "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/console.rs"
click node_uart "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/uart.rs"
click node_monitor "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/monitor.rs"
click node_supervisor "https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/riscv/supervisor_mode.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,node_boot_init,node_boot_config,node_constants,node_user toneBlue
class node_frame_alloc,node_memory_layout,node_virtual_memory,node_memory_types toneAmber
class node_elf,node_loader,node_process_state,node_processing,node_scheduler,node_round_robin,node_sync,node_spin toneMint
class node_trap_handlers,node_uservec,node_syscall_handler,node_syscall_proc,node_syscall_file,node_plic toneRose
class node_console,node_uart,node_monitor,node_supervisor,node_hardware toneIndigo
```

## Components

### Boot

- [Kernel entry](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/main.rs): `src/main.rs`
- [Boot initialization](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/boot/start.rs): `src/boot/start.rs`
- [Machine setup](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/boot/hard_config.rs): `src/boot/hard_config.rs`
- [System constants](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/config/constants.rs): `src/config/constants.rs`

### Memory

- [Frame allocator](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/frame_alloc.rs): `src/memory/frame_alloc.rs`
- [Physical layout](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/memory_layout.rs): `src/memory/memory_layout.rs`
- [Virtual memory](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/memory/virtual_memory.rs): `src/memory/virtual_memory.rs`
- [Address and page tables](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/riscv/memory_types.rs): `src/riscv/memory_types.rs`

### Processes

- [ELF loader](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/file/elf.rs): `src/file/elf.rs`
- [Process loader](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/loader.rs): `src/proc/loader.rs`
- [Process state](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/control_types.rs): `src/proc/control_types.rs`
- [Process management](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/processing.rs): `src/proc/processing.rs`
- [Scheduler](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/scheduler.rs): `src/proc/scheduler.rs`
- [Round-robin policy](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/round_robin.rs): `src/proc/round_robin.rs`
- [Process synchronization](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/sync.rs): `src/proc/sync.rs`
- [Spin mutex](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/proc/spin.rs): `src/proc/spin.rs`

### Traps and syscalls

- [Trap handling](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/trap_handlers.rs): `src/trap/trap_handlers.rs`
- [User trap vector](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/uservec.rs): `src/trap/uservec.rs`
- [Syscall dispatch](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_handler.rs): `src/trap/syscall_handler.rs`
- [Process syscalls](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_proc.rs): `src/trap/syscall_proc.rs`
- [File syscalls](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/syscall_file.rs): `src/trap/syscall_file.rs`
- [Interrupt controller](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/trap/plic.rs): `src/trap/plic.rs`

### Platform I/O and RISC-V

- [Console](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/console.rs): `src/io/console.rs`
- [UART](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/uart.rs): `src/io/uart.rs`
- [Display monitor](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/io/monitor.rs): `src/io/monitor.rs`
- [Supervisor controls](https://github.com/bouezleonardo/polvoss-kernel/blob/main/src/riscv/supervisor_mode.rs): `src/riscv/supervisor_mode.rs`

### Other components

- **User process**
- **RISC-V hardware**

## Connections

- Kernel entry → Boot initialization: starts (evidence: `src/main.rs`)
- Boot initialization → Machine setup: configures (evidence: `src/boot/start.rs`)
- Boot initialization → Frame allocator: initializes (evidence: `src/boot/start.rs`)
- Boot initialization → Virtual memory: initializes (evidence: `src/boot/start.rs`)
- Boot initialization → Process management: starts (evidence: `src/boot/start.rs`)
- Boot initialization → Scheduler: starts (evidence: `src/boot/start.rs`)
- Boot initialization → Trap handling: installs (evidence: `src/boot/start.rs`)
- Machine setup → Supervisor controls: configures (evidence: `src/boot/hard_config.rs`)
- Frame allocator → Physical layout: bounds allocation (evidence: `src/memory/frame_alloc.rs`)
- Frame allocator → Spin mutex: locks allocator (evidence: `src/memory/frame_alloc.rs`)
- Virtual memory → Frame allocator: allocates frames (evidence: `src/memory/virtual_memory.rs`)
- Virtual memory → Physical layout: maps layout (evidence: `src/memory/virtual_memory.rs`)
- Virtual memory → Address and page tables: uses page tables (evidence: `src/memory/virtual_memory.rs`)
- Virtual memory → Process state: updates address space (evidence: `src/memory/virtual_memory.rs`)
- Process loader → ELF loader: loads image (evidence: `src/proc/loader.rs`)
- Process loader → Virtual memory: maps process (evidence: `src/proc/loader.rs`)
- Process loader → Process state: sets process state (evidence: `src/proc/loader.rs`)
- Process management → Process loader: loads init process (evidence: `src/proc/processing.rs`)
- Process management → Virtual memory: creates process image (evidence: `src/proc/processing.rs`)
- Process management → Process state: manages PCB (evidence: `src/proc/processing.rs`)
- Scheduler → Process management: switches processes (evidence: `src/proc/scheduler.rs`)
- Scheduler → Round-robin policy: selects process (evidence: `src/proc/scheduler.rs`)
- Process management → Spin mutex: uses locks (evidence: `src/proc/processing.rs`)
- Process synchronization → Process management: schedules waiters (evidence: `src/proc/sync.rs`)
- Process synchronization → Spin mutex: protects queues (evidence: `src/proc/sync.rs`)
- User process → User trap vector: traps into
- User trap vector → Trap handling: dispatches trap (evidence: `src/trap/uservec.rs`)
- Trap handling → Syscall dispatch: dispatches syscall (evidence: `src/trap/trap_handlers.rs`)
- Syscall dispatch → Process syscalls: dispatches process calls (evidence: `src/trap/syscall_handler.rs`)
- Syscall dispatch → File syscalls: dispatches file calls (evidence: `src/trap/syscall_handler.rs`)
- Process syscalls → Process management: operates on processes (evidence: `src/trap/syscall_proc.rs`)
- Trap handling → Interrupt controller: handles device interrupts (evidence: `src/trap/trap_handlers.rs`)
- Trap handling → Supervisor controls: reads trap state (evidence: `src/trap/trap_handlers.rs`)
- Boot initialization → Console: initializes (evidence: `src/boot/start.rs`)
- Console → Display monitor: writes display (evidence: `src/io/console.rs`)
- Console → UART: uses serial I/O (evidence: `src/io/console.rs`)
- Console → Process management: copies user data (evidence: `src/io/console.rs`)
- Interrupt controller → Process management: signals device event (evidence: `src/trap/plic.rs`)
- RISC-V hardware → Interrupt controller: raises interrupts
- RISC-V hardware → UART: provides device I/O
