# mazunix/mazu architecture

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

- Interactive diagram: https://gitdiagram.com/mazunix/mazu
- Repository: https://github.com/mazunix/mazu

## Overview

1. **Overall shape**
   - Mazu is a bare-metal RISC-V 64-bit RTOS kernel with a small user/task layer built into the same image.
   - The repository is organized around one kernel, one architecture port (`arch/riscv64`), a set of in-kernel subsystems (`kernel/`), a small user-space program set (`user/`), and a packed runtime root filesystem (`rootfs/`).

2. **Boot and hardware bring-up**
   - Execution starts in `arch/riscv64/entry.c`, with OpenSBI handing off control and passing the FDT.
   - Early boot discovers QEMU `virt` hardware via FDT, initializes the UART, PLIC, paging, and per-CPU state, then enters the kernel init path.
   - This is the main boundary between firmware/SoC initialization and the portable kernel core.

3. **Configuration and build-time shaping**
   - Build-time behavior is driven by Kconfig (`configs/Kconfig`) plus defconfigs/fragments.
   - The build system generates config headers and conditionally compiles major features like SMP, TCP, UDP, WebSocket, semihosting, virtio-blk, and writable ramfs.
   - This means architecture diagrams should show features as compile-time gates, not runtime plugins.

4. **Kernel initialization and dependency graph**
   - `kernel/init/main.c` and `kernel/init/initgraph.c` run subsystem startup in dependency order.
   - The init sequence brings up memory, paging, allocators, scheduler services, networking, and optional protocol/service tasks.
   - The dependency graph is important: services are not launched ad hoc; they are started after their supporting infrastructure is ready.

5. **Scheduling and CPU topology**
   - The scheduler is a core subsystem under `kernel/sched/`, designed for hard real-time and SMP from the start.
   - Each hart has per-CPU run queues, callout state, and timing data; `gp` is used for per-CPU access on RISC-V.
   - Timer interrupts and traps drive preemption, wakeups, load balancing, and deadline maintenance; long-lived kernel service work runs as ordinary scheduled tasks.

6. **Memory management and object allocation**
   - Physical page allocation lives in `kernel/mm/buddy.c`, while general kernel virtual allocation is handled by `kernel/mm/kvalloc.c`.
   - Higher-level subsystems rely heavily on pool and arena allocators from `include/mazu/` for fixed-size objects and request-scoped temporary data.
   - Page tables are set up in `arch/riscv64/paging.c` using Sv39 with identity-mapped kernel memory and shared user mappings, so the architecture is “single address space with controlled user regions,” not full process isolation.

7. **Process, syscall, and user-pointer boundary**
   - Process creation, ELF loading, spawning, signals, pipes, and syscalls are in `kernel/proc/`.
   - Syscall handling is guarded by per-process allow-lists and user-pointer validation, with `uaccess` enforcing boundary checks before data crosses kernel/user space.
   - The process boundary is therefore security-sensitive but intentionally lightweight: no separate VM per task, just VMA-style containment and policy checks.

8. **Synchronization and blocking primitives**
   - The kernel provides Linux-like synchronization primitives in `kernel/sync/`: mutexes, rwlocks, semaphores, barriers, condvars, futexes, and synchronization handles.
   - Wait queues and timer callouts connect these primitives to scheduler sleep/wakeup behavior.
   - Lock ordering is a first-class concern, and many kernel subsystems assume the shared lock hierarchy enforced by lockdep-style checks.

9. **Filesystem stack and namespace model**
   - Filesystems are split between synthetic namespaces and data-backed storage under `kernel/fs/`.
   - `vfs.c` dispatches path lookups across mounted filesystems; `devfs`, `procfs`, and `netfs` expose kernel state as files, while `ramfs` and `sfs` store actual content.
   - `bcache` only exists for the disk-backed path; synthetic filesystems are generated on demand and not page-cached.
   - This is a major architectural boundary: system control and observability are file-based rather than ioctl/socket-based.

10. **Networking pipeline**
   - Networking starts at the QEMU virtio-mmio device driver (`drivers/net/virtio_mmio.c`) and flows into `kernel/net/netdev.c`.
   - Packets are processed through ARP, IPv4, ICMP, UDP, DNS/DHCP/mDNS, and TCP, with send-buffer and retransmission logic managed in-kernel.
   - The TCP implementation is connection-oriented but not socket-based; callers use direct kernel APIs such as `tcp_conn_listen`, `tcp_conn_accept`, `tcp_conn_connect`, `tcp_conn_send`, and `tcp_conn_recv`.
   - This makes the network stack a direct service layer inside the kernel, not a user-space networking subsystem.

11. **Web service and user-facing runtime**
   - The main application workload is the kernel-integrated web server in `user/net/web.c`.
   - It serves static assets from `rootfs/web/` and exposes REST endpoints for stats, TCP/ARP tables, klog, filesystem browsing, shell I/O, and SSE/WebSocket streaming.
   - The “shell” and telemetry interfaces are ordinary tasks using the TCP stack, so the web UI is not a separate external appliance; it is part of the kernel workload model.

12. **Root filesystem and packaged runtime content**
   - `rootfs/` is archived into the kernel image at build time.
   - It contains boot-time configuration, example content, and the web UI assets used by the HTTP server.
   - This means the runtime content model is static-at-build, mutable-at-boot only where the in-kernel filesystems allow it.

13. **Testing, verification, and CI**
   - The repository has both kernel tests (`tests/`) and host-side tests under `tests/host/`.
   - CI scripts cover formatting, static analysis, security checks, QEMU runs, TAP networking, and semihosted self-tests.
   - Tooling is centered on cross-compilation for RISC-V, QEMU `virt`, and Linux-hosted automation; architecture diagrams should include these as the primary dev/test environment.

14. **External dependencies and execution environment**
   - The system assumes OpenSBI firmware, QEMU `virt`, virtio devices, PLIC, and either SLIRP or TAP networking during development.
   - Host-side scripts also support network setup and TLS relay/proxying for development-time access to the plaintext HTTP service.
   - These are important infrastructure boundaries because they shape boot, I/O, and how the kernel’s networking is exercised in practice.

Main entry points: [`kernel/init/initgraph.c`](https://github.com/mazunix/mazu/blob/main/kernel/init/initgraph.c) (Init graph), [`kernel/net/tcp.c`](https://github.com/mazunix/mazu/blob/main/kernel/net/tcp.c) (Protocols), [`arch/riscv64/entry.c`](https://github.com/mazunix/mazu/blob/main/arch/riscv64/entry.c) (Boot entry), [`kernel/proc/proc.c`](https://github.com/mazunix/mazu/blob/main/kernel/proc/proc.c) (Proc/syscall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot_arch["Boot & Arch"]
  node_entry["Boot entry<br/>arch boot<br/>[entry.c]"]
  node_fdt["FDT parse<br/>arch fdt<br/>[fdt.c]"]
  node_paging["Paging<br/>sv39 mmu<br/>[paging.c]"]
  node_trap["Traps<br/>irq/trap<br/>[trap.c]"]
  node_sbi["SBI/semihost<br/>fw bridge<br/>[sbi.c]"]
end

subgraph group_kernel_core["Kernel Core"]
  node_main_init["Kernel init<br/>init main<br/>[main.c]"]
  node_initgraph["Init graph<br/>startup dep graph<br/>[initgraph.c]"]
  node_sched["Scheduler<br/>rt/smp sched<br/>[core.c]"]
  node_waitq["Wait queues<br/>block/wakeup<br/>[waitqueue.c]"]
  node_mm["Memory mgr<br/>page/kv alloc<br/>[buddy.c]"]
  node_proc["Proc/syscall<br/>proc & syscall<br/>[proc.c]"]
  node_uaccess["Uaccess<br/>user boundary<br/>[uaccess.c]"]
  node_sync["Sync primitives<br/>locks/blocking<br/>[mutex.c]"]
  node_timers["Timers<br/>callout/timer<br/>[callout.c]"]
end

subgraph group_fs_storage["FS & Storage"]
  node_vfs["VFS<br/>namespace switch<br/>[vfs.c]"]
  node_synthfs["Synthetic FS<br/>dev/proc/net fs<br/>[devfs.c]"]
  node_backedfs["Backed FS<br/>ram/sfs storage<br/>[ramfs.c]"]
  node_bcache["Block cache<br/>disk cache<br/>[bcache.c]"]
end

subgraph group_net_stack["Networking"]
  node_netdev["Netdev<br/>net ingress<br/>[netdev.c]"]
  node_virtio_net["Virtio MMIO<br/>driver<br/>[virtio_mmio.c]"]
  node_proto["Protocols<br/>arp/ip/tcp/udp<br/>[tcp.c]"]
  node_sendbuf["Send buffers<br/>tcp tx/rx<br/>[send_buf.c]"]
end

subgraph group_runtime_user["Runtime & User"]
  node_webui["Web server<br/>user task<br/>[web.c]"]
  node_shell["Shell task<br/>user task<br/>[shell.c]"]
  node_rootfs["RootFS<br/>packed archive<br/>[index.html]"]
end

subgraph group_build_test["Build & Test"]
  node_kconfig["Kconfig<br/>config build"]
  node_scripts["Build scripts<br/>tooling<br/>[make_config.sh]"]
  node_tests["Tests<br/>[tests-initgraph.c]"]
end

node_entry -->|"discovers"| node_fdt
node_entry -->|"sets up"| node_paging
node_entry -->|"installs"| node_trap
node_entry -->|"calls"| node_sbi
node_entry -->|"enters"| node_main_init
node_main_init -->|"orders"| node_initgraph
node_initgraph -->|"starts"| node_mm
node_initgraph -->|"starts"| node_sched
node_initgraph -->|"starts"| node_sync
node_initgraph -->|"starts"| node_vfs
node_initgraph -->|"starts"| node_netdev
node_sched -->|"uses"| node_waitq
node_timers -->|"drives"| node_sched
node_proc -->|"guards"| node_uaccess
node_proc -->|"spawns"| node_sched
node_proc -->|"blocks on"| node_sync
node_vfs -->|"dispatches"| node_synthfs
node_vfs -->|"mounts"| node_backedfs
node_backedfs -->|"uses"| node_bcache
node_virtio_net -->|"feeds"| node_netdev
node_netdev -->|"routes"| node_proto
node_proto -->|"buffers"| node_sendbuf
node_proto -->|"serves"| node_webui
node_proto -->|"supports"| node_shell
node_rootfs -->|"packages"| node_webui
node_kconfig -.->|"gates"| node_main_init
node_kconfig -.->|"gates"| node_proto
node_kconfig -.->|"gates"| node_backedfs
node_scripts -->|"drives"| node_kconfig
node_tests -->|"verifies"| node_main_init
node_tests -->|"verifies"| node_proc
node_tests -->|"verifies"| node_proto

click node_entry "https://github.com/mazunix/mazu/blob/main/arch/riscv64/entry.c"
click node_fdt "https://github.com/mazunix/mazu/blob/main/arch/riscv64/fdt.c"
click node_paging "https://github.com/mazunix/mazu/blob/main/arch/riscv64/paging.c"
click node_trap "https://github.com/mazunix/mazu/blob/main/arch/riscv64/trap.c"
click node_sbi "https://github.com/mazunix/mazu/blob/main/arch/riscv64/sbi.c"
click node_main_init "https://github.com/mazunix/mazu/blob/main/kernel/init/main.c"
click node_initgraph "https://github.com/mazunix/mazu/blob/main/kernel/init/initgraph.c"
click node_sched "https://github.com/mazunix/mazu/blob/main/kernel/sched/core.c"
click node_waitq "https://github.com/mazunix/mazu/blob/main/kernel/sched/waitqueue.c"
click node_mm "https://github.com/mazunix/mazu/blob/main/kernel/mm/buddy.c"
click node_proc "https://github.com/mazunix/mazu/blob/main/kernel/proc/proc.c"
click node_uaccess "https://github.com/mazunix/mazu/blob/main/kernel/proc/uaccess.c"
click node_sync "https://github.com/mazunix/mazu/blob/main/kernel/sync/mutex.c"
click node_timers "https://github.com/mazunix/mazu/blob/main/kernel/timer/callout.c"
click node_vfs "https://github.com/mazunix/mazu/blob/main/kernel/fs/vfs.c"
click node_synthfs "https://github.com/mazunix/mazu/blob/main/kernel/fs/devfs.c"
click node_backedfs "https://github.com/mazunix/mazu/blob/main/kernel/fs/ramfs.c"
click node_bcache "https://github.com/mazunix/mazu/blob/main/kernel/fs/bcache.c"
click node_netdev "https://github.com/mazunix/mazu/blob/main/kernel/net/netdev.c"
click node_virtio_net "https://github.com/mazunix/mazu/blob/main/drivers/net/virtio_mmio.c"
click node_proto "https://github.com/mazunix/mazu/blob/main/kernel/net/tcp.c"
click node_sendbuf "https://github.com/mazunix/mazu/blob/main/kernel/net/send_buf.c"
click node_webui "https://github.com/mazunix/mazu/blob/main/user/net/web.c"
click node_shell "https://github.com/mazunix/mazu/blob/main/user/shell.c"
click node_rootfs "https://github.com/mazunix/mazu/blob/main/rootfs/web/index.html"
click node_kconfig "https://github.com/mazunix/mazu/tree/main/configs/Kconfig"
click node_scripts "https://github.com/mazunix/mazu/blob/main/scripts/make_config.sh"
click node_tests "https://github.com/mazunix/mazu/blob/main/tests/tests-initgraph.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_entry,node_fdt,node_paging,node_trap,node_sbi toneBlue
class node_main_init,node_initgraph,node_sched,node_waitq,node_mm,node_proc,node_uaccess,node_sync,node_timers toneAmber
class node_vfs,node_synthfs,node_backedfs,node_bcache toneMint
class node_netdev,node_virtio_net,node_proto,node_sendbuf toneRose
class node_webui,node_shell,node_rootfs toneIndigo
class node_kconfig,node_scripts,node_tests toneTeal
```

## Components

### Boot & Arch

RISC-V bring-up, traps, paging, and hardware handoff

- [Boot entry](https://github.com/mazunix/mazu/blob/main/arch/riscv64/entry.c): arch boot · OpenSBI handoff, early CPU/FDT bring-up, and kernel entry · `arch/riscv64/entry.c`
- [FDT parse](https://github.com/mazunix/mazu/blob/main/arch/riscv64/fdt.c): arch fdt · Device tree discovery and platform description · `arch/riscv64/fdt.c`
- [Paging](https://github.com/mazunix/mazu/blob/main/arch/riscv64/paging.c): sv39 mmu · Kernel/user mapping setup and address space control · `arch/riscv64/paging.c`
- [Traps](https://github.com/mazunix/mazu/blob/main/arch/riscv64/trap.c): irq/trap · Interrupt and exception entry for preemption and syscall boundaries · `arch/riscv64/trap.c`
- [SBI/semihost](https://github.com/mazunix/mazu/blob/main/arch/riscv64/sbi.c): fw bridge · Firmware calls and semihosting support · `arch/riscv64/sbi.c`

### Kernel Core

Initialization, scheduling, memory, sync, timers, and proc control

- [Kernel init](https://github.com/mazunix/mazu/blob/main/kernel/init/main.c): init main · Top-level subsystem startup sequence · `kernel/init/main.c`
- [Init graph](https://github.com/mazunix/mazu/blob/main/kernel/init/initgraph.c): startup dep graph · Ordered dependency-based service startup · `kernel/init/initgraph.c`
- [Scheduler](https://github.com/mazunix/mazu/blob/main/kernel/sched/core.c): rt/smp sched · Per-CPU run queues, deadlines, wakeups, and preemption · `kernel/sched/core.c`
- [Wait queues](https://github.com/mazunix/mazu/blob/main/kernel/sched/waitqueue.c): block/wakeup · Sleep and wake coordination for blocking paths · `kernel/sched/waitqueue.c`
- [Memory mgr](https://github.com/mazunix/mazu/blob/main/kernel/mm/buddy.c): page/kv alloc · Physical pages and kernel virtual allocations · `kernel/mm/buddy.c`
- [Proc/syscall](https://github.com/mazunix/mazu/blob/main/kernel/proc/proc.c): proc & syscall · ELF loading, spawn, signals, pipes, syscalls, and user-pointer checks · `kernel/proc/proc.c`
- [Uaccess](https://github.com/mazunix/mazu/blob/main/kernel/proc/uaccess.c): user boundary · Validation boundary for copying data across kernel/user space · `kernel/proc/uaccess.c`
- [Sync primitives](https://github.com/mazunix/mazu/blob/main/kernel/sync/mutex.c): locks/blocking · Mutexes, rwlocks, semaphores, barriers, condvars, futexes, and handles · `kernel/sync/mutex.c`
- [Timers](https://github.com/mazunix/mazu/blob/main/kernel/timer/callout.c): callout/timer · Callouts and POSIX timers feeding scheduling and blocking · `kernel/timer/callout.c`

### FS & Storage

Virtual filesystems and storage-backed content

- [VFS](https://github.com/mazunix/mazu/blob/main/kernel/fs/vfs.c): namespace switch · Mount and pathname dispatch across filesystems · `kernel/fs/vfs.c`
- [Synthetic FS](https://github.com/mazunix/mazu/blob/main/kernel/fs/devfs.c): dev/proc/net fs · Generated namespaces for device, proc, and network state · `kernel/fs/devfs.c`
- [Backed FS](https://github.com/mazunix/mazu/blob/main/kernel/fs/ramfs.c): ram/sfs storage · RAM and disk-backed filesystem implementations · `kernel/fs/ramfs.c`
- [Block cache](https://github.com/mazunix/mazu/blob/main/kernel/fs/bcache.c): disk cache · Cache layer used by storage-backed filesystems · `kernel/fs/bcache.c`

### Networking

Device ingress through protocol stack and kernel TCP/UDP services

- [Netdev](https://github.com/mazunix/mazu/blob/main/kernel/net/netdev.c): net ingress · Kernel network device front-end · `kernel/net/netdev.c`
- [Virtio MMIO](https://github.com/mazunix/mazu/blob/main/drivers/net/virtio_mmio.c): driver · QEMU virtio network device driver · `drivers/net/virtio_mmio.c`
- [Protocols](https://github.com/mazunix/mazu/blob/main/kernel/net/tcp.c): arp/ip/tcp/udp · ARP, IPv4, ICMP, UDP, DNS/DHCP/mDNS, and TCP processing · `kernel/net/tcp.c`
- [Send buffers](https://github.com/mazunix/mazu/blob/main/kernel/net/send_buf.c): tcp tx/rx · TCP buffering and retransmission support · `kernel/net/send_buf.c`

### Runtime & User

Built-in user tasks and packaged root filesystem

- [Web server](https://github.com/mazunix/mazu/blob/main/user/net/web.c): user task · Kernel-integrated HTTP service and telemetry shell · `user/net/web.c`
- [Shell task](https://github.com/mazunix/mazu/blob/main/user/shell.c): user task · Built-in interactive task using TCP services · `user/shell.c`
- [RootFS](https://github.com/mazunix/mazu/blob/main/rootfs/web/index.html): packed archive · Build-time archived runtime content and web assets · `rootfs/web/index.html`

### Build & Test

Configuration, scripts, and verification environment

- [Kconfig](https://github.com/mazunix/mazu/tree/main/configs/Kconfig): config build · Compile-time feature selection and generated configuration · `configs/Kconfig`
- [Build scripts](https://github.com/mazunix/mazu/blob/main/scripts/make_config.sh): tooling · Defconfig, image packing, and test automation scripts · `scripts/make_config.sh`
- [Tests](https://github.com/mazunix/mazu/blob/main/tests/tests-initgraph.c): kernel/host tests · In-kernel and host-side verification suite · `tests/tests-initgraph.c`

## Connections

- Boot entry → FDT parse: discovers · Boot code uses FDT to identify the QEMU virt platform
- Boot entry → Paging: sets up · Early architecture bring-up establishes kernel mappings
- Boot entry → Traps: installs · Trap/interrupt handling is initialized during boot
- Boot entry → SBI/semihost: calls · Firmware services and semihosting are accessed through SBI
- Boot entry → Kernel init: enters · Architecture handoff transfers control into kernel initialization
- Kernel init → Init graph: orders · Subsystem startup follows dependency graph sequencing
- Init graph → Memory mgr: starts · Memory management comes up early for all later subsystems
- Init graph → Scheduler: starts · Scheduler services are required for kernel tasks and services
- Init graph → Sync primitives: starts · Locking and blocking primitives underpin most kernel services
- Init graph → VFS: starts · Namespace services are initialized after core infrastructure
- Init graph → Netdev: starts · Networking is enabled once base kernel services exist
- Scheduler → Wait queues: uses · Blocking primitives rely on scheduler sleep and wake paths
- Timers → Scheduler: drives · Timer events trigger preemption and deadline maintenance
- Proc/syscall → Uaccess: guards · Syscalls validate pointers before copying user data
- Proc/syscall → Scheduler: spawns · Processes and kernel tasks are scheduled on the run queues
- Proc/syscall → Sync primitives: blocks on · Pipes, signals, and waits use synchronization primitives
- VFS → Synthetic FS: dispatches · Devfs, procfs, and netfs expose kernel state as files
- VFS → Backed FS: mounts · Ramfs and sfs hold actual file content
- Backed FS → Block cache: uses · Storage-backed paths pass through the block cache
- Virtio MMIO → Netdev: feeds · Device driver hands packets to the kernel networking front-end
- Netdev → Protocols: routes · Ingress and egress flow into protocol processing
- Protocols → Send buffers: buffers · TCP send/receive and retransmission use internal buffers
- Protocols → Web server: serves · Kernel TCP APIs support the built-in HTTP service
- Protocols → Shell task: supports · Interactive shell task communicates over the TCP stack
- RootFS → Web server: packages · Static web assets are archived into the kernel image
- Kconfig → Kernel init: gates · Build-time options shape which services are compiled and started
- Kconfig → Protocols: gates · TCP, UDP, DNS, DHCP, and WebSocket features are compile-time selected
- Kconfig → Backed FS: gates · Writable ramfs and storage options are controlled at build time
- Build scripts → Kconfig: drives · Defconfig and image-generation tooling produce the build configuration
- Tests → Kernel init: verifies · Kernel tests exercise init ordering and core subsystems
- Tests → Proc/syscall: verifies · Process, syscall, and uaccess behavior are covered by tests
- Tests → Protocols: verifies · Network protocol behavior is checked by kernel and host tests