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/rcore-os/rCore 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.

GO — Healthy across all four use cases

• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{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 rcore-os/rCore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rcore-os/rCore.

What it runs against: a local clone of rcore-os/rCore — 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 rcore-os/rCore | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1018 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rcore-os/rCore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rcore-os/rCore.git
#   cd rCore
#
# 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 rcore-os/rCore and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "kernel/src/arch" \\
  && ok "kernel/src/arch" \\
  || miss "missing critical file: kernel/src/arch"
test -f "crate/memory/src/lib.rs" \\
  && ok "crate/memory/src/lib.rs" \\
  || miss "missing critical file: crate/memory/src/lib.rs"
test -f "crate/memory/src/memory_set/mod.rs" \\
  && ok "crate/memory/src/memory_set/mod.rs" \\
  || miss "missing critical file: crate/memory/src/memory_set/mod.rs"
test -f "kernel/Cargo.toml" \\
  && ok "kernel/Cargo.toml" \\
  || miss "missing critical file: kernel/Cargo.toml"
test -f "kernel/src/arch/aarch64/boot/entry.S" \\
  && ok "kernel/src/arch/aarch64/boot/entry.S" \\
  || miss "missing critical file: kernel/src/arch/aarch64/boot/entry.S"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1018 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~988d)"
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/rcore-os/rCore"
  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 is a Rust implementation of an x86_64/RISC-V/AArch64/MIPS-compatible teaching OS kernel that can execute Linux userspace programs and syscalls. It provides a functioning monolithic kernel with memory management (paging, swapping, COW), process scheduling, file systems, networking, signals, and async I/O—all written in Rust rather than C/assembly. Monorepo structure: kernel/ directory contains the main OS kernel, user/ contains userspace utilities and libc tests, crate/ contains reusable library crates (memory, hal, etc.) published as separate packages. The memory crate (crate/memory/src/) is modular with handlers for different backing stores (byframe, file, delay, shared) and swapping strategies (FIFO, enhanced clock). Architecture-specific code branches into kernel/arch/ subdirectories.

Operating systems students and educators at Tsinghua University (and similar institutions) who want to learn kernel design through a readable, modern Rust codebase instead of traditional C-based uCore; also potential contributors interested in seeing how Linux syscall compatibility is achieved in a teaching OS context.

NO LONGER MAINTAINED—the README explicitly states maintenance has ceased in favor of zCore, arceos, and the rCore-Tutorial-Book-v3. The project achieved substantial completeness (Linux-compatible syscalls, multi-architecture support, network stack) but is now an archived reference implementation rather than actively developed software. Active development shifted to successor projects around 2021-2022.

High abandonment risk: the main repository is explicitly unmaintained and directs users to alternative projects. Minimal dependency footprint (only log and spin crates in memory module) reduces supply-chain risk, but lack of recent commits means no security patches or compatibility updates with modern Rust toolchains. Single-maintainer history (@wangrunji0408 for core x86_64/memory/process modules) creates knowledge silos even when active.

Nothing—the repository is archived. The last activity was teaching coursework and reports in 2020 (docs/2020_OS/). Development efforts migrated to zCore (Rust uCore in hypervisor mode), arceos (modular teaching OS), and rCore-Tutorial-Book-v3 (modern Rust OS course material).

git clone https://github.com/rcore-os/rCore.git --recursive && cd rCore/user && make sfsimg PREBUILT=1 ARCH=x86_64 && cd ../kernel && make run ARCH=x86_64 LOG=info (requires Rust, QEMU >= 4.1.0, and musl-based GCC toolchains from https://musl.cc/)

Daily commands: make run ARCH=x86_64 LOG=info in kernel/ directory; supports ARCH={x86_64,riscv32,riscv64,aarch64,mips32}. Build prerequisite: rustup component add rust-src llvm-tools-preview. Optionally: docker run -it -v $PWD:$PWD -w $PWD wangrunji0408/rcore (pre-configured container).

• kernel/src/arch — Multi-architecture abstraction layer defining CPU-specific entry points and board support for x86_64, RISCV, AArch64, and MIPS—every kernel port starts here
• crate/memory/src/lib.rs — Core memory management abstractions including paging, swapping, and memory set handling—foundational for all address translation and page allocation
• crate/memory/src/memory_set/mod.rs — Virtual memory space management and memory region handlers—critical for process isolation and memory layout enforcement
• kernel/Cargo.toml — Kernel workspace and dependency configuration including architecture and board selection—controls build matrix for all supported platforms
• kernel/src/arch/aarch64/boot/entry.S — AArch64 bootstrap assembly—demonstrates firmware handoff and low-level initialization pattern replicated across other architectures
• crate/memory/src/paging/mod.rs — Page table abstraction and mock implementations—provides MMU interface used by all memory management subsystems
• crate/memory/src/memory_set/handler/mod.rs — Pluggable memory region handlers (linear, file-backed, CoW, shared)—enables flexible memory mapping strategies for ELF loading and anonymous pages

Add support for a new architecture

1. Create architecture directory following existing pattern (x86_64, riscv, aarch64, mips) (kernel/src/arch)
2. Implement CPU initialization and interrupt handling in entry.S and mod.rs files (kernel/src/arch/{newarch}/boot/entry.S)
3. Add board-specific support (timer, mailbox, I/O) mirroring raspi3 structure (kernel/src/arch/{newarch}/board/{boardname}/mod.rs)
4. Update Cargo.toml with new architecture feature flag and conditional compilation (kernel/Cargo.toml)
5. Define linker script for memory layout matching firmware expectations (kernel/src/arch/{newarch}/boot/linker.ld)

Add a new memory region handler

1. Create handler module implementing Handler trait from mod.rs (crate/memory/src/memory_set/handler/{newhandler}.rs)
2. Register handler variant in MemoryHandler enum and match logic (crate/memory/src/memory_set/handler/mod.rs)
3. Implement required methods: clone(), handle_page_fault(), and introspection methods (crate/memory/src/memory_set/handler/{newhandler}.rs)
4. Update memory_set module to expose handler creation factory methods (crate/memory/src/memory_set/mod.rs)

Implement a new page replacement algorithm

1. Create new swapper module in swap directory with Swapper trait (crate/memory/src/swap/{newalgorithm}.rs)
2. Implement select_victim() to identify evictable page frames (crate/memory/src/swap/{newalgorithm}.rs)
3. Register swapper in swap module's factory and trait object dispatch (crate/memory/src/swap/mod.rs)
4. Add unit tests using mock_swapper as reference for testing pattern (crate/memory/src/swap/mock_swapper.rs)

Add a new board variant for existing architecture

1. Create board directory mirroring raspi3 structure with mod.rs (kernel/src/arch/{arch}/board/{newboard}/mod.rs)
2. Implement peripheral drivers (timer, interrupt controller, I/O) (kernel/src/arch/{arch}/board/{newboard}/timer.rs)
3. Create memory layout linker script for new board's MMIO and RAM regions (kernel/src/arch/{arch}/board/{newboard}/linker.ld)
4. Add board feature gate to arch module and Cargo.toml (kernel/Cargo.toml)

• Rust — Memory safety without garbage collection; exploits type system for page table invariants and prevents use-after-free in virtual memory operations
• Multi-architecture abstraction layer — Single kernel codebase supports x86_64, RISCV, AArch64, MIPS with conditional compilation; reduces maintenance burden and teaching complexity
• Pluggable memory handlers and swappers — Enables runtime selection of memory region strategies (file-backed, CoW, shared) and page replacement algorithms without recompilation
• Spin-based synchronization — Lightweight, lock-free coordination for page table updates; avoids heavy mutex overhead in interrupt handlers

• Trait-based handler and swapper abstraction

  • Why: Flexibility for different memory backing stores and eviction policies
  • Consequence: Dynamic dispatch overhead on every page fault; ~5-10% performance cost vs. inline implementations

• Shared codebase across 4 ISA variants

  • Why: Single OS kernel reduces teaching iteration time and maintenance burden
  • Consequence: Some architecture-specific optimizations sacrificed; conditional compilation increases binary complexity

• Linux-compatible syscall interface

  • Why: Allows running unmodified Linux userspace binaries and tools for validation
  • Consequence: Tight coupling to Linux ABI; harder to evolve custom syscall interface; must maintain musl compatibility

• Page-level CoW implementation

  • Why: Simple fork() semantics without explicit child-parent bookkeeping
  • Consequence: Write-heavy workloads trigger excessive page faults; no optimization for read-mostly sharing patterns

• Not

Recursive submodules required (--recursive flag mandatory in git clone). PREBUILT=1 flag skips recompiling musl libc for user programs (omitting it requires musl-based GCC toolchains in PATH). Rust edition 2018 syntax used; some older code may not compile with latest stable without edition migration. The Makefile assumes QEMU is in PATH and supports x86_64 as default ARCH; arm/mips setups require explicit ARCH=. No containerized test environment provided despite Dockerfile presence—Docker image is for manual dev work, not CI.

• Copy-on-Write (COW) — rCore implements COW in crate/memory/src/cow.rs to optimize fork() syscalls by deferring page copies until write; understanding this pattern is essential for memory efficiency in process creation
• Page Swapping & Eviction Policies — The swap/ module implements FIFO and enhanced clock algorithms to manage memory overcommit; learners must understand how eviction decisions impact performance and how to swap pages to disk
• Virtual Memory & Address Translation — The paging/ and addr.rs modules implement page table walks and TLB-like abstractions; this is core to understanding how virtual addresses become physical addresses in modern kernels
• Linux Syscall Interface & ABI Compatibility — rCore achieves Linux compatibility by implementing the Linux x86_64 syscall ABI; learners must understand syscall numbers, register conventions, and how to route syscalls to kernel handlers
• Memory-Mapped I/O & Handler Pattern — The memory_set/handler/ module uses pluggable handlers (ByFrame, File, Delay, Shared) to abstract different backing stores for memory regions; this pattern decouples memory allocation from I/O policy
• Interrupt & Exception Handling in Bare-Metal Rust — The kernel must trap into exception handlers for syscalls and page faults; rCore demonstrates how to write interrupt handlers in Rust without stdlib, critical for OS-level control flow
• Multi-Architecture Porting & Conditional Compilation — rCore supports x86_64, RISC-V, AArch64, and MIPS via kernel/arch/; learners should understand how to write portable kernel code using Rust feature gates and architecture-specific modules

• rcore-os/zCore — Official successor to rCore: ports the same kernel to hypervisor mode (Zircon microkernel), where active development continues
• rcore-os/arceos — Next-generation modular teaching OS built on lessons from rCore; offers pluggable components and is actively maintained as the recommended learning platform
• rcore-os/rCore-Tutorial-Book-v3 — Official Rust OS course material derived from rCore; comprehensive book covering OS concepts with runnable examples, replaces rCore as the primary teaching resource
• chyyuu/ucore_os_plus — Original C/assembly uCore OS from Tsinghua that rCore was ported from; provides architectural reference for understanding design decisions
• phil-opp/blog_os — Foundational 'Writing an OS in Rust' project that rCore builds upon; demonstrates core bare-metal Rust patterns used throughout rCore

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 memory management handlers

The crate/memory/src/memory_set/handler/ directory contains multiple handler implementations (byframe.rs, delay.rs, file.rs, linear.rs, shared.rs) but there are no visible test files. Given this is a critical OS component handling memory allocation strategies, adding unit tests would improve reliability and make it easier for contributors to understand handler behavior.

• [ ] Create crate/memory/src/memory_set/handler/tests/ directory with test modules
• [ ] Add unit tests for each handler (test_byframe.rs, test_delay.rs, test_file.rs, test_linear.rs, test_shared.rs) covering initialization, allocation, and edge cases
• [ ] Add integration tests in crate/memory/tests/ that verify handler interactions with the main memory_set module
• [ ] Update crate/memory/Cargo.toml with dev-dependencies if needed (e.g., proptest for property-based testing)

Add swap algorithm benchmarking suite

The crate/memory/src/swap/ directory implements multiple page replacement algorithms (enhanced_clock.rs, fifo.rs) but lacks performance benchmarks. Since swap performance directly impacts OS responsiveness, adding benchmarks would help evaluate trade-offs between strategies and prevent regressions.

• [ ] Create crate/memory/benches/swap_benchmarks.rs with Criterion benchmarks
• [ ] Add benchmarks comparing FIFO vs Enhanced Clock under various workload patterns (sequential, random, working-set)
• [ ] Update Cargo.toml with bench dependencies (criterion) and configure bench targets
• [ ] Document benchmark results and methodology in docs/performance_analysis/ or README

Create migration guide from deprecated rCore to successor projects

The README explicitly states 'NO LONGER MAINTAINED' and links to successor projects (zCore, arceos, rCore-Tutorial-Book-v3). However, there's no migration guide helping existing users understand which successor to adopt and how to transition. This would improve user experience and reduce confusion.

• [ ] Create docs/MIGRATION.md explaining the status of each successor project and recommended use cases
• [ ] Add a comparison table in docs/MIGRATION.md showing feature parity between rCore, zCore, and arceos
• [ ] Document specific steps for migrating crate/memory/ functionality to successor projects
• [ ] Update README.md to prominently link to the new migration guide at the top

• Add unit tests for crate/memory/src/cow.rs: COW (copy-on-write) implementation exists but has zero visible test coverage; a new contributor could add tests for fork behavior and page protection transitions without deep kernel knowledge
• Document syscall handler routing in kernel/src/syscall/: No inline docs explain how Linux syscall numbers map to kernel handlers; adding rustdoc comments explaining the dispatch mechanism would help future learners understand the Linux compatibility layer
• Add integration test for memory swapping with FIFO vs enhanced_clock: crate/memory/src/swap/ defines two swapping strategies but only mock_swapper.rs exists for testing; a real integration test comparing eviction order under memory pressure would validate the swapping logic

The rCore repository presents a moderate security posture with primary concerns centered on its maintenance status and dependency management. The project is explicitly unmaintained, meaning security vulnerabilities will not receive patches. The memory crate has outdated dependencies (spin 0.5) that should be upgraded. The project's complexity as an OS kernel with low-level memory operations inherently requires careful unsafe code management, which cannot be fully assessed from static analysis of the file structure alone. For production use, migration to maintained alternatives (zCore, arceos) is strongly recommended. If continued internal use is necessary, establish dedicated security review and patching processes.

• Medium · Outdated Dependency: spin 0.5 — crate/memory/Cargo.toml. The crate/memory/Cargo.toml specifies 'spin = "0.5"' which is outdated. The spin crate has evolved significantly, and version 0.5 may have known issues or lack security improvements from newer versions. Current stable versions are much higher (0.9+). Fix: Update spin dependency to the latest stable version (e.g., 0.9 or higher) to benefit from security patches and bug fixes. Review CHANGELOG for breaking changes before upgrading.
• Low · No Dependency Version Pinning Strategy — crate/memory/Cargo.toml. Dependencies in Cargo.toml use caret requirements (implicit ^0.4 for log, ^0.5 for spin), which allow minor version updates automatically. This could introduce unexpected behavior changes if transitive dependencies are compromised or have breaking changes. Fix: Consider implementing a more explicit versioning strategy. For security-critical projects, consider using exact versions or range specifiers with careful monitoring of updates.
• Medium · Project No Longer Maintained — README.md. The README explicitly states 'NO LONGER MAINTAINED' with references to newer projects (zCore, arceos, rCore-Tutorial-Book-v3). This means security vulnerabilities will not be patched, and the codebase may contain unresolved issues. Fix: This repository should not be used for production systems. Users should migrate to actively maintained alternatives like zCore or arceos. If continued use is necessary, establish an internal security review process and patch vulnerabilities independently.
• Low · Memory Safety in Unsafe Code — crate/memory/src/ (particularly paging/, swap/, cow.rs). As an OS kernel written in Rust with memory management components (swap, paging, memory_set handlers), the codebase likely contains unsafe blocks. Without visibility into the actual implementation, potential memory safety issues could exist in areas like page table manipulation, swap handlers, and COW (copy-on-write) operations. Fix: Conduct thorough safety audits of all unsafe code blocks, particularly in memory management subsystems. Use tools like miri and cargo-audit regularly. Consider using safe abstractions where possible and document safety invariants clearly.

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.