# fullavatar/rupios architecture

> Architecture diagram of the GitHub repository fullavatar/rupios, 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/fullavatar/rupios
- Repository: https://github.com/fullavatar/rupios
- Video tour (about a minute): https://gitdiagram.com/fullavatar/rupios/video

## Overview

RuPiOs is a small bare-metal Raspberry Pi OS kernel with a serial command shell for system and interrupt diagnostics. The main workflow starts at the ARM boot entry, initializes UART and the GIC, then accepts shell commands and reports results over serial. Timer commands query or schedule the architectural timer; IRQ vectors dispatch through the exception handler to acknowledge GIC interrupts and update timer state. The README is empty, so capabilities are inferred from the sampled source; unsampled runtime behavior is not expanded.

Main entry points: [`src/system/exceptions.rs`](https://github.com/fullavatar/rupios/blob/main/src/system/exceptions.rs) (Exception handlers), [`src/shell.rs`](https://github.com/fullavatar/rupios/blob/main/src/shell.rs) (Command shell), [`src/drivers/uart.rs`](https://github.com/fullavatar/rupios/blob/main/src/drivers/uart.rs) (UART driver), [`src/system/timer.rs`](https://github.com/fullavatar/rupios/blob/main/src/system/timer.rs) (Timer services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and kernel"]
  node_boot_entry["ARM boot entry<br/>[boot.rs]"]
  node_kernel["Kernel startup<br/>[main.rs]"]
end

subgraph group_console["Serial shell"]
  node_uart["UART driver<br/>[uart.rs]"]
  node_shell["Command shell<br/>[shell.rs]"]
  node_shell_info["Info commands<br/>[shell.rs]"]
  node_shell_timer["Timer commands<br/>[shell.rs]"]
  node_shell_irq["IRQ commands<br/>[shell.rs]"]
  node_shell_exception["Exception commands<br/>[shell.rs]"]
end

subgraph group_interrupts["Interrupts and timer"]
  node_gic["GIC driver<br/>[gic.rs]"]
  node_vectors["Exception vectors<br/>[boot.rs]"]
  node_exception_handler["Exception handlers<br/>[exceptions.rs]"]
  node_irq_control["IRQ control<br/>[interrupts.rs]"]
  node_timer["Timer services<br/>[timer.rs]"]
end

node_serial_user(("Serial user"))

node_boot_entry -->|"enters"| node_kernel
node_kernel -->|"initializes"| node_uart
node_kernel -->|"initializes"| node_gic
node_kernel -->|"starts"| node_shell
node_serial_user -->|"sends input"| node_uart
node_uart -->|"prints output"| node_serial_user
node_shell -->|"reads and writes"| node_uart
node_shell -->|"dispatches"| node_shell_info
node_shell -->|"dispatches"| node_shell_timer
node_shell -->|"dispatches"| node_shell_irq
node_shell -->|"dispatches"| node_shell_exception
node_shell_info -->|"prints results"| node_uart
node_shell_info -->|"queries"| node_timer
node_shell_info -->|"queries level"| node_exception_handler
node_shell_info -->|"queries status"| node_gic
node_shell_timer -->|"queries or schedules"| node_timer
node_shell_irq -->|"enables IRQs"| node_irq_control
node_shell_irq -->|"reads count"| node_timer
node_shell_irq -->|"queries pending"| node_gic
node_shell_exception -->|"triggers fault"| node_exception_handler
node_vectors -->|"dispatches exceptions"| node_exception_handler
node_vectors -->|"dispatches IRQs"| node_exception_handler
node_exception_handler -->|"acknowledges and completes"| node_gic
node_exception_handler -->|"handles timer IRQ"| node_timer
node_exception_handler -->|"prints fault details"| node_uart
node_timer -->|"reschedules IRQ"| node_timer

click node_boot_entry "https://github.com/fullavatar/rupios/blob/main/src/boot.rs"
click node_kernel "https://github.com/fullavatar/rupios/blob/main/src/main.rs"
click node_uart "https://github.com/fullavatar/rupios/blob/main/src/drivers/uart.rs"
click node_shell "https://github.com/fullavatar/rupios/blob/main/src/shell.rs"
click node_shell_info "https://github.com/fullavatar/rupios/blob/main/src/shell.rs"
click node_shell_timer "https://github.com/fullavatar/rupios/blob/main/src/shell.rs"
click node_shell_irq "https://github.com/fullavatar/rupios/blob/main/src/shell.rs"
click node_shell_exception "https://github.com/fullavatar/rupios/blob/main/src/shell.rs"
click node_gic "https://github.com/fullavatar/rupios/blob/main/src/drivers/gic.rs"
click node_vectors "https://github.com/fullavatar/rupios/blob/main/src/boot.rs"
click node_exception_handler "https://github.com/fullavatar/rupios/blob/main/src/system/exceptions.rs"
click node_irq_control "https://github.com/fullavatar/rupios/blob/main/src/system/interrupts.rs"
click node_timer "https://github.com/fullavatar/rupios/blob/main/src/system/timer.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_boot_entry,node_kernel,node_serial_user toneBlue
class node_uart,node_shell,node_shell_info,node_shell_timer,node_shell_irq,node_shell_exception toneAmber
class node_gic,node_vectors,node_exception_handler,node_irq_control,node_timer toneMint
```

## Components

### Boot and kernel

- [ARM boot entry](https://github.com/fullavatar/rupios/blob/main/src/boot.rs): `src/boot.rs`
- [Kernel startup](https://github.com/fullavatar/rupios/blob/main/src/main.rs): `src/main.rs`

### Serial shell

- [UART driver](https://github.com/fullavatar/rupios/blob/main/src/drivers/uart.rs): `src/drivers/uart.rs`
- [Command shell](https://github.com/fullavatar/rupios/blob/main/src/shell.rs): `src/shell.rs`
- [Info commands](https://github.com/fullavatar/rupios/blob/main/src/shell.rs): `src/shell.rs`
- [Timer commands](https://github.com/fullavatar/rupios/blob/main/src/shell.rs): `src/shell.rs`
- [IRQ commands](https://github.com/fullavatar/rupios/blob/main/src/shell.rs): `src/shell.rs`
- [Exception commands](https://github.com/fullavatar/rupios/blob/main/src/shell.rs): `src/shell.rs`

### Interrupts and timer

- [GIC driver](https://github.com/fullavatar/rupios/blob/main/src/drivers/gic.rs): `src/drivers/gic.rs`
- [Exception vectors](https://github.com/fullavatar/rupios/blob/main/src/boot.rs): `src/boot.rs`
- [Exception handlers](https://github.com/fullavatar/rupios/blob/main/src/system/exceptions.rs): `src/system/exceptions.rs`
- [IRQ control](https://github.com/fullavatar/rupios/blob/main/src/system/interrupts.rs): `src/system/interrupts.rs`
- [Timer services](https://github.com/fullavatar/rupios/blob/main/src/system/timer.rs): `src/system/timer.rs`

### Other components

- **Serial user**

## Connections

- ARM boot entry → Kernel startup: enters
- Kernel startup → UART driver: initializes
- Kernel startup → GIC driver: initializes
- Kernel startup → Command shell: starts
- Serial user → UART driver: sends input
- UART driver → Serial user: prints output
- Command shell → UART driver: reads and writes
- Command shell → Info commands: dispatches
- Command shell → Timer commands: dispatches
- Command shell → IRQ commands: dispatches
- Command shell → Exception commands: dispatches
- Info commands → UART driver: prints results
- Info commands → Timer services: queries
- Info commands → Exception handlers: queries level
- Info commands → GIC driver: queries status
- Timer commands → Timer services: queries or schedules
- IRQ commands → IRQ control: enables IRQs
- IRQ commands → Timer services: reads count
- IRQ commands → GIC driver: queries pending
- Exception commands → Exception handlers: triggers fault
- Exception vectors → Exception handlers: dispatches exceptions
- Exception vectors → Exception handlers: dispatches IRQs
- Exception handlers → GIC driver: acknowledges and completes
- Exception handlers → Timer services: handles timer IRQ
- Exception handlers → UART driver: prints fault details
- Timer services → Timer services: reschedules IRQ