egos-2000: a 2000-line RISC-V teaching OS you can read end to end

What egos-2000 is for, and who it is for

The README states the vision directly: help every student read all the code of a teaching operating system. That sentence sets the audience. egos-2000 is not aimed at people who need an operating system; it is aimed at people who need to understand one. The repository counts 2000 lines exactly, as the README's cloc output shows, spread across 30 C files, 9 headers, 3 assembly files and one makefile. A student can read that in a semester.

The project also ships a book. The EGOS book contains 9 course projects based on egos-2000, and the acknowledgements name two courses that have used it: Northeastern CS4973/6640 and Cornell CS4411/5411. That is the clearest signal of intended use. If you are assembling a kernel course or working through one, the code and the exercises are designed to fit together. If you want a small RISC-V kernel to study on your own hardware, it works for that too, provided your hardware is on the supported list.

What it is not for is production. Nothing in the README claims otherwise. The scope is a teaching system that runs on QEMU and RISC-V boards, and the line budget is a constraint the project treats as a feature.

The earth, grass and application layers

The name egos comes from the architecture. Three layers, each with a defined job.

The earth layer implements hardware-specific abstractions: the tty and disk device interface, plus timer and memory management interfaces. This is the layer that changes when the hardware changes. The grass layer implements hardware-independent abstractions: the process control block and the system call interface. Above that, the application layer implements the file system, the shell and user commands.

The interface between layers is not loose prose. The README points to the definitions of struct earth and struct grass in library/egos.h as the specification of the layer interface. That is a useful design decision for a teaching codebase: instead of documenting a boundary in a wiki that drifts, the boundary is a C struct the compiler enforces. A student who wants to port egos-2000 to new hardware reads two struct definitions and knows what must be implemented.

The repository layout mirrors the layers: earth/, grass/, apps/ and library/ sit at the top level next to Makefile, README.md and USAGES.md. The build reflects the split as well. The makefile defines APPS_DEPS over apps/*.* and library/egos.h plus library/*/*, and EGOS_DEPS over earth/*, grass/* and the same library paths, so application and kernel objects rebuild on different dependency sets.

One consequence of this design is worth naming. A three-layer split with a struct interface is clean, but it is also a fixed shape. If you want to explore a different kernel structure, egos-2000 is not the codebase to do it in, because the layers are the pedagogical content.

Building egos-2000 and running it on QEMU

The README defers running instructions to USAGES.md, so treat that file as the authoritative source for the full sequence. The Makefile shows what the build expects.

The toolchain comes in two flavours. Setting TOOLCHAIN=GNU selects the official GNU toolchain binaries, riscv32-unknown-elf-gcc with matching objdump and objcopy. Leaving it unset uses the pre-compiled xPack binaries, riscv-none-elf-gcc and its companions. Pick one and make sure it is on your PATH.

The default target builds the user application ELFs, the system application ELFs and build/release/egos.elf. The compile flags in the makefile are rv32ima_zicsr with the ilp32 ABI, so the output is 32-bit RISC-V with the M, A and Zicsr extensions. The linker script is library/elf/egos.lds and the link is -nostdlib -lc -lgcc, which means the kernel does not depend on a hosted C library.

QEMU is set to qemu-system-riscv32 in the makefile, and the board variable defaults to tangnano20k. For the emulator path you want the 32-bit RISC-V system emulator, not the 64-bit one. The README's cloc command is also worth running yourself if the line count matters to you:

cloc egos-2000 --exclude-ext=md

That is the whole first-use story: build with one of two toolchains, boot the resulting ELF under qemu-system-riscv32 or flash it to a supported board. The README does not walk through the QEMU invocation or the board flashing steps; USAGES.md is where those live.

The 2000-line budget is a real constraint, not a slogan

The cloc output in the README is the project's own accounting: 1592 lines of C, 258 lines of headers, 92 lines of assembly, 58 lines of makefile, summing to 2000 exactly. That exactness is deliberate, and it has costs that a reader should weigh before adopting the project.

A kernel that fits in 2000 lines cannot carry a broad device driver set. The earth layer covers tty, disk, timer and memory management. There is no network stack in the described scope, no filesystem beyond what the application layer implements, and no SMP story in the README. If your interest is in those areas, egos-2000 will not teach them and you will spend your time adding rather than reading.

The line budget also means the code is dense. 1592 lines of C for process control, system calls, a file system, a shell and user commands leaves little room for defensive layers. A student reading it sees the essential path and not much else. That is the intent, but it also means egos-2000 is a poor model for how production kernels handle error paths, because the error handling that would be there is largely absent.

There is a further practical limit: the README does not document rollback, upgrade procedures or a migration path between releases. Releases exist (v4.0.0 in July 2026, v3.0.2 in November 2025, v3.0.1 in February 2025), but what changes between them, and what a student who built course materials on v3.0.1 should do, is not stated in the README.

Alternatives: xv6 and the difference in approach

The obvious comparison for a teaching operating system is xv6, the MIT kernel used in operating systems courses. The difference is not quality; it is what the code is optimised for.

xv6 is larger and closer to a conventional Unix design. It has a fuller process model, a more complete file system and a body of commentary that maps to a well-known textbook. If your course is structured around Unix internals and you want students to see a recognisable system, xv6 fits that shape better. Its size is part of the point: students modify a system that already resembles the real thing.

egos-2000 takes the opposite bet. It shrinks to 2000 lines and organises those lines into three explicit layers with struct-defined interfaces. The goal is that a student can read every line, not that the system resembles a production kernel. The RISC-V focus reinforces this: the build targets rv32ima_zicsr and the README points to the RISC-V privileged ISA manuals for background, so the project sits close to the architecture rather than abstracting it away.

There is also a hardware dimension. egos-2000 runs on QEMU and on real RISC-V boards, and the acknowledgements record ports to mriscv (a SystemVerilog processor) and to the Allwinner D1 with Sipeed's Lichee RV64 Nezha module. If your teaching setup involves FPGA boards or embedded RISC-V hardware, that porting history is relevant. If you need a kernel with a large driver ecosystem, neither egos-2000 nor xv6 is the right tool, and you should be looking at Linux.

Maintenance, releases and the licence question

The repository is not archived, and the last push was on 2026-08-16. The most recent release is v4.0.0, dated 2026-07-22, following v3.0.2 in November 2025 and v3.0.1 in February 2025. The cadence is roughly one release every several months, which is consistent with a project maintained by an academic author alongside teaching duties rather than a product team.

For a course, that cadence matters less than the stability of the interfaces. The layer interfaces live in library/egos.h, so a change there propagates to everything. The README does not describe a deprecation policy or a compatibility guarantee between releases. If you build course materials on a specific release, pin it and treat upgrades as a deliberate task.

The licence field is NOASSERTION, which means the repository's licence could not be automatically classified. The repository does contain a LICENSE file at the top level, and the Makefile carries a copyright notice reading "(C) 2026, Cornell University. All rights reserved." Those two facts sit awkwardly together for anyone planning to reuse the code outside a classroom. Read the LICENSE file itself before you redistribute or build on egos-2000, and if the terms matter to your institution, get them checked rather than inferring from the repository metadata. This article is not legal advice.

Editorial conclusion

Adopt egos-2000 if you are teaching or studying operating system internals and want a codebase you can finish reading, or if you want a small RISC-V kernel to port. Do not adopt it as a production or general-purpose OS: the README frames it as a teaching system, and the 2000-line budget means device support and features are deliberately narrow. Before committing, verify that your toolchain matches the Makefile's two supported options, that your board is one of arty_a7_35t, arty_a7_100t, arty_s7_50 or tangnano20k, and read USAGES.md for the run steps the README defers to.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. yhzhang0128/egos-2000 on GitHub