# jimingkang/xv6-aarch64 architecture

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

- Interactive diagram: https://gitdiagram.com/jimingkang/xv6-aarch64
- Repository: https://github.com/jimingkang/xv6-aarch64

## Overview

This repository combines an xv6 AArch64 teaching OS with a trace-to-animation workflow. The documented user path is to run the GDB trace client, export its log as a web animation, then inspect the generated HTML. The kernel’s process, virtual-memory, syscall, and filesystem areas are retained as distinct OS responsibilities, but their internal call graph is not established by the excerpts. The README supports the trace-tool sequence; unsampled kernel connections are omitted rather than inferred.

Main entry points: [`kernel/fs.c`](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/fs.c) (Inodes and paths), [`tools/run_trace_commands.py`](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/run_trace_commands.py) (GDB trace client), [`tools/export_trace_web.py`](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/export_trace_web.py) (Web exporter), [`kernel/bio.c`](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/bio.c) (Block cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trace["Trace workflow"]
  node_runtrace["GDB trace client"]
  node_tracecore["Trace capture<br/>[trace_xv6.py]"]
  node_export["Web exporter"]
  node_animation["Trace animation<br/>[animate_trace.py]"]
  node_html["Trace HTML"]
end

subgraph group_proc["Process and syscall"]
  node_process["Process scheduler<br/>[proc.c]"]
  node_syscall["Syscall dispatch<br/>[syscall.c]"]
  node_sysfile["File syscalls<br/>[sysfile.c]"]
  node_exec["Program loading<br/>[exec.c]"]
end

subgraph group_memory["Memory and hardware"]
  node_boot["Kernel startup<br/>[main.c]"]
  node_vm["Virtual memory<br/>[vm.c]"]
  node_allocator["Page allocator<br/>[kalloc.c]"]
end

subgraph group_storage["Filesystem and I/O"]
  node_fs["Inodes and paths<br/>[fs.c]"]
  node_cache["Block cache<br/>[bio.c]"]
  node_disk["Virtio disk<br/>[virtio_disk.c]"]
  node_log["Filesystem log<br/>[log.c]"]
end

subgraph group_user["User programs"]
  node_shell["Command shell<br/>[sh.c]"]
  node_init["Init process<br/>[init.c]"]
  node_commands["User commands"]
  node_tests["User syscall tests<br/>[usertests.c]"]
end

node_engineer(("Engineer"))

node_engineer -->|"runs trace"| node_runtrace
node_runtrace -->|"then exports"| node_export
node_export -->|"creates animation"| node_html
node_engineer -->|"inspects"| node_html
node_fs -->|"reads blocks"| node_cache
node_fs -->|"logs updates"| node_log

click node_runtrace "https://github.com/jimingkang/xv6-aarch64/blob/main/tools/run_trace_commands.py"
click node_tracecore "https://github.com/jimingkang/xv6-aarch64/blob/main/tools/trace_xv6.py"
click node_export "https://github.com/jimingkang/xv6-aarch64/blob/main/tools/export_trace_web.py"
click node_animation "https://github.com/jimingkang/xv6-aarch64/blob/main/tools/animate_trace.py"
click node_boot "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/main.c"
click node_process "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/proc.c"
click node_syscall "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/syscall.c"
click node_sysfile "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/sysfile.c"
click node_exec "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/exec.c"
click node_vm "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/vm.c"
click node_allocator "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/kalloc.c"
click node_fs "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/fs.c"
click node_cache "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/bio.c"
click node_disk "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/virtio_disk.c"
click node_log "https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/log.c"
click node_shell "https://github.com/jimingkang/xv6-aarch64/blob/main/user/sh.c"
click node_init "https://github.com/jimingkang/xv6-aarch64/blob/main/user/init.c"
click node_commands "https://github.com/jimingkang/xv6-aarch64/tree/main/user"
click node_tests "https://github.com/jimingkang/xv6-aarch64/blob/main/user/usertests.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_runtrace,node_tracecore,node_export,node_animation,node_html toneBlue
class node_process,node_syscall,node_sysfile,node_exec toneAmber
class node_boot,node_vm,node_allocator toneMint
class node_fs,node_cache,node_disk,node_log toneRose
class node_shell,node_init,node_commands,node_tests,node_engineer toneIndigo
```

## Components

### Trace workflow

- [GDB trace client](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/run_trace_commands.py): `tools/run_trace_commands.py`
- [Trace capture](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/trace_xv6.py): `tools/trace_xv6.py`
- [Web exporter](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/export_trace_web.py): `tools/export_trace_web.py`
- [Trace animation](https://github.com/jimingkang/xv6-aarch64/blob/main/tools/animate_trace.py): `tools/animate_trace.py`
- **Trace HTML**

### Process and syscall

- [Process scheduler](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/proc.c): `kernel/proc.c`
- [Syscall dispatch](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/syscall.c): `kernel/syscall.c`
- [File syscalls](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/sysfile.c): `kernel/sysfile.c`
- [Program loading](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/exec.c): `kernel/exec.c`

### Memory and hardware

- [Kernel startup](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/main.c): `kernel/main.c`
- [Virtual memory](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/vm.c): `kernel/vm.c`
- [Page allocator](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/kalloc.c): `kernel/kalloc.c`

### Filesystem and I/O

- [Inodes and paths](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/fs.c): `kernel/fs.c`
- [Block cache](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/bio.c): `kernel/bio.c`
- [Virtio disk](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/virtio_disk.c): `kernel/virtio_disk.c`
- [Filesystem log](https://github.com/jimingkang/xv6-aarch64/blob/main/kernel/log.c): `kernel/log.c`

### User programs

- [Command shell](https://github.com/jimingkang/xv6-aarch64/blob/main/user/sh.c): `user/sh.c`
- [Init process](https://github.com/jimingkang/xv6-aarch64/blob/main/user/init.c): `user/init.c`
- [User commands](https://github.com/jimingkang/xv6-aarch64/tree/main/user): `user`
- [User syscall tests](https://github.com/jimingkang/xv6-aarch64/blob/main/user/usertests.c): `user/usertests.c`

### Other components

- **Engineer**

## Connections

- Engineer → GDB trace client: runs trace (evidence: `README`)
- GDB trace client → Web exporter: then exports (evidence: `README`)
- Web exporter → Trace HTML: creates animation (evidence: `README`)
- Engineer → Trace HTML: inspects (evidence: `README`)
- Inodes and paths → Block cache: reads blocks (evidence: `kernel/fs.c`)
- Inodes and paths → Filesystem log: logs updates (evidence: `kernel/fs.c`)