EGOS-2000: A 2000-Line Teaching Operating System (Earth and Grass Architecture)

EGOS-2000: A Teaching Operating System in 2000 Lines of Code

Introduction In the landscape of operating systems teaching, EGOS-2000 stands out as a compact yet complete project designed to help every student read and understand the entire codebase of a teaching OS. With exactly 2000 lines of code, this implementation brings together the essential components needed to run on both QEMU and RISC-V boards. The project is a gateway into practical systems learning, offering a three-layer architecture that makes the internals approachable while preserving real-world relevance. The accompanying EGOS book expands on this by presenting nine course projects grounded in the egos-2000 foundation. A visual snapshot of the project can be seen in the image included here.

[Image: egos-2000]

Vision: Readable Code, Accessible OS Knowledge The core vision behind EGOS-2000 is ambitieous and empowering: to enable every student to read all the code of a teaching operating system. The aim is not to overwhelm with complexity but to present a faithful, minimal system where every line matters and every component has a clear purpose. The project demonstrates that a practical operating system can be understood line-by-line and still be functional on modern emulation and hardware platforms.

Key ideas in the vision include:

• A deliberately small, transparent kernel that fits into a few thousand lines of code, yet implements essential OS functionality.
• Cross-platform operability, with support for QEMU virtualization and RISC-V hardware boards.
• A structured learning path built around layered abstractions—making it easier to trace how high-level concepts map to low-level implementation.

The EGOS book builds on egos-2000 by outlining course projects that use the codebase as a teaching canvas. The book provides guided explorations, exercises, and extended examples that deepen understanding of operating system concepts, scheduling, memory management, I/O, and system calls.

A Practical Snapshot: The 2000 Lines of Code EGOS-2000 is celebrated for its exact code footprint: 2000 lines spread across a compact and cohesive codebase. This precision is more than a curiosity; it is a design decision intended to keep the system approachable while still challenging enough to be meaningful for learning. A closer look at the composition reveals a pragmatic distribution of languages and roles:

• Language mix and file distribution

• C: The largest share, forming the kernel and core logic across multiple files.

• C/C++ headers: Essential for definitions and interfaces shared across modules.

• Assembly: A small but important portion used for low-level startup and architecture-specific routines.

• Makefiles: The build scripts that coordinate compilation and linking.

• Exact counts (as counted by the cloc tool)

• Total lines of code: 2000

• C: 1592 lines of code in 30 files

• C/C++ Header: 258 lines of code in 9 files

• Assembly: 92 lines of code in 3 files

• Make: 58 lines of code in 1 file

• The analysis splits the repository into 43 files across languages, with a balance that reflects a kernel designed for clarity over breadth.

What this breakdown means for learners

• A transparent kernel structure: With a tight codebase, students can trace the flow from system calls to low-level hardware interactions without being overwhelmed by boilerplate or extraneous features.
• Focused exploration: The limited scope encourages hands-on experimentation, such as modifying a scheduler or adjusting a memory management policy, and observing the direct consequences.
• A reproducible learning path: The project’s compact size makes it feasible for a single student or a small group to study, modify, and re-build within a reasonable timeframe.

Earth and Grass: A Three-Layer Architecture EGOS-2000 is organized around a three-layer architecture that cleanly separates concerns, from hardware specifics to user-facing applications. The three layers are named to evoke their roles and to provide intuitive boundaries for learning and extension.

1) The Earth Layer: Hardware-Specific Abstractions

• Purpose: This layer interfaces directly with the hardware or hardware emulation, providing the necessary abstractions to access devices and manage the system’s basic resources.
• Responsibilities:
• tty and disk device interfaces
• timer management
• memory management abstractions
• Design note: The Earth layer is where architecture-specific code lives, making it the right place to encapsulate machine-specific details so the upper layers can remain hardware-agnostic.

2) The Grass Layer: Hardware-Independent Abstractions

• Purpose: The Grass layer provides the software abstractions that do not depend on a particular hardware platform.
• Responsibilities:
• Process control blocks (PCBs)
• System call interface and internal process management
• Design note: By abstracting process management and system calls, Grass enables portability of OS logic across different Earth implementations and hardware configurations.

3) The Application Layer: User-Facing Functionality

• Purpose: The Application layer builds on Earth and Grass to present usable OS features that users interact with directly.
• Responsibilities:
• File system operations
• Shell behavior
• User commands
• Design note: This layer demonstrates how the OS exposes services to users and programs, tying together hardware interfaces with practical, everyday tasks.

Key definitions for the layered interface The interface semantics across these layers are codified in the header file egos.h. Within this file, the data structures struct earth and struct grass articulate the interface boundaries and expectations between layers. Reading these definitions provides a concrete view of how the architecture maps to code and how layers communicate.

Guidance for running and using EGOS-2000 For practical use, readers are directed to USAGES.md, which documents how to run egos-2000 in an environment such as QEMU and how to interact with the system. The instruction set manuals for the RISC-V privileged ISA are also linked for learners who want to understand the architectural rules that govern privileged operations and machine modes. The combination of USAGES.md and the ISA manuals equips students with the necessary steps and background to experiment with real hardware semantics and emulator behavior.

Acknowledgements: Appreciation Across the Community The EGOS project is supported by a vibrant community and several organizations and individuals who provided encouragement, feedback, and technical contributions. The acknowledgements reflect a cross-institutional collaboration that highlights the open nature of the project and the educational intent behind it.

• Meta: Recognition for a Facebook fellowship that supported foundational research and development related to EGOS.

• Link: Facebook fellowship program

• Robbert van Renesse (Cornell University): Acknowledged for insights, guidance, and support.

• Link: Robbert van Renesse’s page

• Lorenzo Alvisi (Cornell University): Acknowledged for important perspectives and collaboration.

• Link: Lorenzo Alvisi’s page

• Shan Lu (University of Chicago): Acknowledged for contributions and feedback.

• Link: Shan Lu’s page

• Hakim Weatherspoon (Cornell University): Acknowledged for advice and support.

• Link: Hakim Weatherspoon’s page

• Christopher Batten (Cornell University): Acknowledged for support in the project’s development.

• Link: Christopher Batten’s page

• Cheng Tan: Acknowledged for providing valuable feedback to the EGOS book and for using egos-2000 in Northeastern CS4973/6640.

• Yu-Ju Huang: Acknowledged for feedback and for applying egos-2000 in CS programs at Northeastern and Cornell.

• Haobin Ni: Acknowledged for porting egos-2000 to mriscv, a simple processor architecture described in SystemVerilog.

• Hongbo Zhang: Acknowledged for porting egos-2000 to mriscv and related work.

• Brandon Fusi: Acknowledged for porting egos-2000 to Allwinner D1.

• Sipeed’s Lichee RV64 Nezha compute module: Acknowledged for providing hardware platforms used in the ecosystem.

• Zack Light: Acknowledged for creating a YouTube video introducing egos-2000.

• Christopher Allison: Acknowledged for producing a DOOM video game demonstration that runs on egos-2000.

Contact and ongoing collaboration For questions, collaborations, or further information, the project points to Yunhao Zhang as the contact person. The EGOS community invites educators, students, and researchers to engage, extend, and contribute to the teaching OS ecosystem.

Reading, learning, and extending: Resources for deeper understanding

• The EGOS book provides nine course projects based on egos-2000, offering structured learning paths and deeper dives into OS topics.
• The instruction set manuals for the RISC-V privileged ISA provide the architectural context needed to understand how the hardware interface translates into privileged operations, traps, interrupts, and system-level controls.
• The egos-2000 repository, with its Earth-Grass-Application layering, serves as a practical example of how layered OS design can be taught and explored in an approachable, hands-on way.

Design goals and educational impact

• Clarity through minimalism: The project deliberately emphasizes clarity by keeping the codebase small yet expressive. Each line of code serves a purpose that directly ties back to OS concepts.
• Accessibility for students: The compact size lowers the barrier to entry, enabling students to read, modify, and rebuild the system within the confines of a typical course timeline.
• Realistic teaching experience: Despite its small footprint, egos-2000 simulates essential OS behaviors—device interfaces, memory considerations, process management, and user-level programs—so students gain practical, transferable knowledge.

How to approach EGOS-2000 as a learning project

• Start with the architecture: Examine the Earth and Grass layers to understand hardware interactions and architecture-independent abstractions.
• Read the interfaces: Review the struct earth and struct grass definitions in library/egos.h to understand how layers communicate and what responsibilities each layer holds.
• Trace a use-case end-to-end: Follow a system call from the Application layer through Grass to Earth, observing how the call is serviced and how hardware resources are managed.
• Experiment and extend: Try small changes—such as adjusting memory management policies, tweaking a scheduler decision, or adding a simple user command in the Application layer—and observe how the system behavior changes.
• Consult the USAGES.md and manuals: Use USAGES.md to build and run egos-2000, and consult the RISC-V privilege ISA manuals to deepen architectural understanding.

A note on the visual companion The included image offers a visual anchor for the project and serves as a reminder of the tangible, hands-on nature of EGOS-2000. While the code footprint is intentionally small, the system embodies the broader philosophy of teaching operating systems through concrete, runnable implementations that students can study, modify, and evolve.

Conclusion: A Compact Path to Mastery in Operating Systems EGOS-2000 encapsulates a principled approach to teaching OS concepts: reveal the full code needed for a functioning system, present it in a layered architecture that mirrors hardware reality, and provide guided resources that connect theory to practice. With exactly 2000 lines of code across a carefully chosen set of languages, EGOS-2000 demonstrates that complexity can be tamed without sacrificing educational depth. The project’s three-layer Earth-Grass-Application design, together with the supporting documentation and community acknowledgments, creates a rich, collaborative environment for learners to engage with operating systems in a meaningful, accessible way. Whether you are a student taking your first OS course or an educator seeking a transparent platform for demonstrations and assignments, EGOS-2000 offers a structured, transparent path to understanding the core ideas that power modern computer systems.