# jl115/jos architecture

> Architecture diagram of the GitHub repository jl115/jos, 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/jl115/jos
- Repository: https://github.com/jl115/jos

## Overview

This is a small bare-metal kernel prototype whose sampled runtime entry prints startup diagnostics, then idles. Its UART driver provides character, string, and formatted output through memory-mapped hardware. The source supports the UART call and register-access links shown; boot assembly and the documented future kernel phases were not sampled, so no boot-to-entry or roadmap behavior is inferred.

Main entry points: [`src/drivers/uart/uart.c`](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c) (Format dispatch), [`src/drivers/uart/uart_registry.h`](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart_registry.h) (UART register map), [`src/kernel.c`](https://github.com/jl115/jos/blob/main/src/kernel.c) (Kernel entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel["Kernel startup"]
  node_kernel_main["Kernel entry<br/>[kernel.c]"]
end

subgraph group_uart["UART output"]
  node_uart_printf["Formatted output<br/>[uart.c]"]
  node_format_dispatch["Format dispatch<br/>[uart.c]"]
  node_number_format["Number formatting<br/>[uart.c]"]
  node_uart_putc["Character output<br/>[uart.c]"]
  node_uart_send["UART transmit<br/>[uart.c]"]
  node_uart_wait["Transmit readiness<br/>[uart.c]"]
  node_uart_registers["UART register map<br/>[uart_registry.h]"]
end

node_runtime(("Platform runtime"))
node_uart_device["UART hardware"]

node_runtime -->|"enters"| node_kernel_main
node_kernel_main -->|"prints diagnostics"| node_uart_printf
node_uart_printf -->|"dispatches formats"| node_format_dispatch
node_format_dispatch -->|"outputs characters"| node_uart_putc
node_format_dispatch -->|"formats numbers"| node_number_format
node_number_format -->|"outputs digits"| node_uart_putc
node_uart_putc -->|"sends characters"| node_uart_send
node_uart_send -->|"waits for readiness"| node_uart_wait
node_uart_wait -->|"reads flag register"| node_uart_registers
node_uart_send -->|"writes data register"| node_uart_registers
node_uart_registers -->|"maps MMIO"| node_uart_device

click node_kernel_main "https://github.com/jl115/jos/blob/main/src/kernel.c"
click node_uart_printf "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_format_dispatch "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_number_format "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_uart_putc "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_uart_send "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_uart_wait "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c"
click node_uart_registers "https://github.com/jl115/jos/blob/main/src/drivers/uart/uart_registry.h"

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 toneBlue
class node_uart_printf,node_format_dispatch,node_number_format,node_uart_putc,node_uart_send,node_uart_wait,node_uart_registers toneAmber
class node_runtime,node_uart_device toneIndigo
```

## Components

### Kernel startup

- [Kernel entry](https://github.com/jl115/jos/blob/main/src/kernel.c): `src/kernel.c`

### UART output

- [Formatted output](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [Format dispatch](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [Number formatting](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [Character output](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [UART transmit](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [Transmit readiness](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart.c): `src/drivers/uart/uart.c`
- [UART register map](https://github.com/jl115/jos/blob/main/src/drivers/uart/uart_registry.h): `src/drivers/uart/uart_registry.h`

### Other components

- **Platform runtime**
- **UART hardware**

## Connections

- Platform runtime → Kernel entry: enters
- Kernel entry → Formatted output: prints diagnostics
- Formatted output → Format dispatch: dispatches formats
- Format dispatch → Character output: outputs characters
- Format dispatch → Number formatting: formats numbers
- Number formatting → Character output: outputs digits
- Character output → UART transmit: sends characters
- UART transmit → Transmit readiness: waits for readiness
- Transmit readiness → UART register map: reads flag register
- UART transmit → UART register map: writes data register
- UART register map → UART hardware: maps MMIO