If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/chyyuu/os_kernel_lab shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 7 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live chyyuu/os_kernel_lab repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/chyyuu/os_kernel_lab.

What it runs against: a local clone of chyyuu/os_kernel_lab — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in chyyuu/os_kernel_lab | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1227 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of chyyuu/os_kernel_lab. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/chyyuu/os_kernel_lab.git
#   cd os_kernel_lab
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of chyyuu/os_kernel_lab and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "chyyuu/os_kernel_lab(\\.git)?\\b" \\
  && ok "origin remote is chyyuu/os_kernel_lab" \\
  || miss "origin remote is not chyyuu/os_kernel_lab (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "os/src/main.rs" \\
  && ok "os/src/main.rs" \\
  || miss "missing critical file: os/src/main.rs"
test -f "os/src/task/mod.rs" \\
  && ok "os/src/task/mod.rs" \\
  || miss "missing critical file: os/src/task/mod.rs"
test -f "os/src/mm/mod.rs" \\
  && ok "os/src/mm/mod.rs" \\
  || miss "missing critical file: os/src/mm/mod.rs"
test -f "os/src/trap/mod.rs" \\
  && ok "os/src/trap/mod.rs" \\
  || miss "missing critical file: os/src/trap/mod.rs"
test -f "easy-fs/src/lib.rs" \\
  && ok "easy-fs/src/lib.rs" \\
  || miss "missing critical file: easy-fs/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1227 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1197d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/chyyuu/os_kernel_lab"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

rCore-Tutorial-v3 is an educational Unix-like OS kernel written from scratch in Rust targeting RISC-V 64-bit architecture, running on qemu-system-riscv64 or Kendryte K210 dev boards. It demonstrates a complete 4K+ line-of-code OS with preemptive scheduling, virtual memory, dynamic memory management, a custom block-cache-backed filesystem (easy-fs), and a userspace shell—designed to teach OS fundamentals to beginners without prerequisites in assembly or computer architecture. Monorepo structure: os/ (main kernel in Rust targeting riscv64gc-unknown-none-elf), easy-fs/ (custom block filesystem library), easy-fs-fuse/ (userspace tool to create/manipulate easy-fs images). os/src/ layers platform abstraction (boards/qemu.rs), drivers (block, chardev, gpu, input via virtio), and kernel primitives. Bootloader prebuilt (bootloader/rustsbi-qemu.bin). Docker support for reproducible build environment.

Computer science students and self-taught OS learners who want to understand kernel internals (process/thread management, memory virtualization, filesystems) by reading and modifying a minimal but feature-complete Rust-based OS implementation, rather than studying Linux or other production kernels.

Actively maintained but educational, not production-ready. Last update noted as June 2022 (v3.6.0) with ongoing code updates on chapter branches (chX). GitHub CI/CD configured (.github/workflows/doc-and-test.yml) suggests automated testing. Relatively young project (~2019 inception based on repo structure) with intentionally minimal code size to keep it teachable rather than feature-complete.

Low risk for learning use: single maintainer (Yifan Wu / chyyuu) means potential stalling if unmaintained, but the codebase is frozen at a learning checkpoint. Dependency count is minimal (only clap, rand in easy-fs-fuse; Cargo.lock not visible). Main risks: outdated Rust edition (2018 in easy-fs-fuse), reliance on specific QEMU/rustc versions, and lack of comprehensive test coverage beyond CI workflows. No visible breaking-change policy.

Project appears in maintenance mode: last documented update June 2022. Code is actively available for study and branch-based chapter updates (ch1–ch11 expected based on tutorial model), but no recent GitHub activity visible in provided metadata. CI workflow validates doc generation and tests on push/PR.

git clone https://github.com/chyyuu/os_kernel_lab.git && cd os_kernel_lab && rustup target add riscv64gc-unknown-none-elf && cargo install cargo-binutils --vers =0.3.3 && rustup component add llvm-tools-preview rust-src && make -C os run (requires qemu-system-riscv64 in PATH; see dev-env-info.md for detailed setup).

Daily commands: cd os && make run (builds kernel, links with RustSBI, boots in qemu-system-riscv64 with 128M RAM and VirtIO devices). Alternative: make doc to build tutorial docs, make clean to reset.

• os/src/main.rs — Kernel entry point and main initialization loop; must understand to grasp OS bootstrap sequence and core loop structure.
• os/src/task/mod.rs — Task scheduler and process/thread management abstraction; central to understanding concurrency model and context switching.
• os/src/mm/mod.rs — Memory management facade including page table and heap allocator; critical for understanding virtual memory and address translation.
• os/src/trap/mod.rs — Exception and interrupt handling; essential for understanding how the kernel responds to system calls, timer events, and faults.
• easy-fs/src/lib.rs — EasyFS file system abstraction layer; required to understand file I/O and how user programs interact with persistent storage.
• os/src/syscall/mod.rs — System call dispatcher routing all user-kernel boundaries; needed to understand the OS API surface and request handling.
• os/src/config.rs — Build-time configuration and constants (memory layout, queue sizes, platform specifics); referenced throughout the kernel.

Add a New System Call

1. Define the syscall number in os/src/syscall/mod.rs and handle it in the match statement (os/src/syscall/mod.rs)
2. Implement the syscall logic in the appropriate category file (e.g., process, fs, sync, thread) with the signature fn sys_<name>(args...) -> isize (os/src/syscall/process.rs)
3. Export the syscall function from its module and call it from the dispatcher (os/src/syscall/mod.rs)
4. Add the corresponding wrapper in user/src/lib.rs (libc-like interface) to expose it to user programs (user/src/lib.rs)
5. Test the syscall by creating a binary in user/src/bin/ that calls it (user/src/bin/test_syscall.rs)

Add a New File System Driver

1. Create a new module in easy-fs/src/ implementing the trait objects from easy-fs/src/block_dev.rs (easy-fs/src/lib.rs)
2. Implement BlockDevice trait (read_block, write_block) for your file system (easy-fs/src/block_dev.rs)
3. Implement VfsNode trait (read, write, ls, create, etc.) in your fs module matching easy-fs/src/vfs.rs interface (easy-fs/src/vfs.rs)
4. Register your driver in os/src/drivers/block/mod.rs and initialize it at kernel startup (os/src/drivers/block/mod.rs)
5. Mount the file system in os/src/fs/mod.rs by updating the inode cache initialization (os/src/fs/mod.rs)

Add a New Device Driver

1. Create a module in os/src/drivers/ (e.g., os/src/drivers/mydev/mod.rs) with device initialization and interrupt handlers (os/src/drivers/mydev/mod.rs)
2. Implement device-specific read/write operations and register interrupt handlers with the PLIC via os/src/drivers/plic.rs

Rust edition mismatch: easy-fs-fuse uses 2018 edition; newer Rust may warn. QEMU version sensitivity: README specifies qemu-7.0.0; older/newer versions may have different device models. RustSBI firmware: os/Makefile hardcodes bootloader/rustsbi-qemu.bin; K210 target requires separate bootloader. Memory layout: os/src/config.rs defines 0x80200000 kernel entry; changing this breaks linker script and boot. No std library: alloc required; can't use Vec::from_iter on non-Copy types without explicit collect(). Virtio discovery: drivers/bus/virtio.rs scans MMIO at 0x10001000 (QEMU default); non-standard boards won't boot without modification.

• RISC-V Supervisor Binary Interface (SBI) — RustSBI (bootloader/rustsbi-qemu.bin) provides M-mode runtime environment; understanding SBI delegation (timer, IPI, console) is essential to kernel startup and timer interrupt handling.
• Sv39 Virtual Memory (RISC-V 3-level page tables) — os/src/mm/ implements 48-bit virtual address translation via three-level page tables; Sv39 specifics (page size, PPN/VPN split) differ from x86 and are essential to this codebase's memory isolation.
• VirtIO (Virtual I/O device standard) — os/src/drivers/bus/virtio.rs abstracts QEMU's block, chardev, and input devices; understanding virtio rings, feature negotiation, and MMIO BAR discovery is critical for writing portable device drivers.
• Block cache (write-through caching layer) — easy-fs/src/block_cache.rs trades memory for I/O efficiency; teaches cache coherency and is why easy-fs data structures must be serializable—core to understanding filesystem performance.
• Preemptive Round-Robin Scheduling — os/src/task/mod.rs implements time-sliced scheduling with timer interrupts; understanding context save/restore and task state transitions is foundational to OS concurrency.
• Copy-on-write fork() semantics — User shell relies on fork/exec for process creation; this codebase's fork does full copy (simple but inefficient), teaching why CoW is necessary in real kernels.
• RISC-V trap delegation and trap handlers — os/src/trap.rs dispatches all exceptions (syscalls, page faults, timer interrupts) via scause register; mastering trap vector setup, context frames, and delegation is essential to bare-metal Rust kernels.

• rcore-os/rCore — Production-grade RISC-V OS in Rust from the same team; rCore-Tutorial is the simplified teaching version extracted from this
• rust-embedded/riscv — Official RISC-V HAL crate for Rust; used by this project for CSR access and exception handling primitives
• mit-pdos/xv6-riscv — Reference C-based RISC-V OS from MIT; rCore-Tutorial mirrors xv6's pedagogical approach and syscall set but in Rust
• rcore-os/rCore-Tutorial-Book-v3 — Companion Chinese documentation and lecture notes explaining each chapter of this codebase; essential reading alongside source code
• torvalds/linux — Linux kernel for reference on real-world implementations of scheduler, memory management, and VFS interfaces taught here in minimal form

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for easy-fs filesystem modules

The easy-fs crate lacks dedicated unit tests for core filesystem operations. The modules in easy-fs/src/ (bitmap.rs, block_cache.rs, vfs.rs, efs.rs, layout.rs) handle critical filesystem logic but have no visible test suite. Adding tests would catch regressions and serve as documentation for filesystem behavior.

• [ ] Create easy-fs/src/lib.rs test module with #[cfg(test)] blocks
• [ ] Add unit tests for bitmap.rs covering allocation/deallocation edge cases
• [ ] Add unit tests for block_cache.rs covering cache eviction and coherency
• [ ] Add unit tests for vfs.rs and efs.rs covering inode creation, file operations, and directory traversal
• [ ] Run tests locally: cd easy-fs && cargo test
• [ ] Document test coverage in easy-fs README

Add integration tests for easy-fs-fuse disk image creation

The easy-fs-fuse tool (easy-fs-fuse/src/main.rs) is a critical utility for generating filesystem images but has no tests validating its output. Adding integration tests would ensure disk images are created correctly and catch bugs in the image generation pipeline before they reach the kernel.

• [ ] Create easy-fs-fuse/tests/ directory with integration test module
• [ ] Write test that invokes easy-fs-fuse with sample file tree and validates output disk image structure
• [ ] Add test verifying bitmap, inode table, and data block layout match specifications from easy-fs/src/layout.rs
• [ ] Create test fixture directory with sample files (empty, text, binary) to test image generation
• [ ] Run tests: cd easy-fs-fuse && cargo test --test '*'
• [ ] Document test usage in easy-fs-fuse README

Add missing CI workflow for easy-fs and easy-fs-fuse crates

The .github/workflows/doc-and-test.yml workflow exists but likely only covers the main os crate. The easy-fs and easy-fs-fuse crates are standalone libraries that should be tested independently. Adding a dedicated workflow would catch issues in filesystem code without rebuilding the full kernel.

• [ ] Create .github/workflows/easy-fs-test.yml workflow file
• [ ] Add job to test easy-fs: cargo test -p easy-fs --all-features
• [ ] Add job to test easy-fs-fuse: cargo test -p easy-fs-fuse
• [ ] Add cargo check and clippy linting for both crates
• [ ] Configure workflow to run on push to branches and pull requests
• [ ] Verify workflow executes successfully by creating a test PR

• Add unit tests to easy-fs/src/bitmap.rs for bitmap operations (free/alloc bit sequences) to validate allocation correctness—bitmap is critical for inode/block management but currently untested.
• Write integration tests in os/tests/ that verify syscall behavior (exit codes, fork/exec return values) using a test harness; current CI only runs docs, no functional OS tests.
• Document the memory layout diagram and page table structure in os/src/mm/mod.rs and os/src/config.rs with inline comments and update README.md with a visual architecture diagram—beginners struggle to visualize 48-bit VA mapping and kernel/user separation.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.