Library / SDK
yhzhang0128/egos-2000 avatar
yhzhang0128/egos-2000

egos-2000: two thousand lines, three layers, four boards

Envision a future where everyone can read all the code of an educational operating system.

3,719 stars322 forksCNOASSERTION

At a glance

What is it?
A teaching operating system small enough that the claim it makes is that you can read all of it, layered as hardware abstraction, kernel, and applications, and buildable for an emulator or one of four named boards. The build system is written to be read too.
Who is it for?
This project fits a course on operating systems, or a reader who wants a whole system in one sitting rather than a subsystem from a large one. Two things to know before you start.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 91 days ago.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • yhzhang0128/egos-20003,719 ★ · +89
Star history
Repository2026-09-242026-11-15
yhzhang0128/egos-20003.6k3.7k

89 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The line count is a measurement, not a claim

The vision statement is that every student should be able to read all the code, and the number attached to it is two thousand lines. The readme does not assert that; it counts it, with the output of a source-counting tool pasted in, with markdown files excluded.

shell
# The cloc utility is used to count the lines of code.
> cloc egos-2000 --exclude-ext=md

What survives in the visible rows is roughly sixteen hundred lines of C across thirty files, plus a couple of hundred in headers across nine, with blanks and comments counted separately. That distinction matters for a teaching project, because the useful property is not the total but the fact that it is finite and verifiable: you can count it yourself, and the count will not be wildly off. It also tells you the shape of the code, which is mostly C with a small amount of hand-written assembly underneath.

Three layers named after a lawn metaphor

The system name comes from its architecture, and the metaphor is a description of the design rather than decoration. The bottom layer handles hardware, exposing a terminal and disk device interface plus a timer and memory management interface. The middle layer is hardware independent and provides the process control block and the system call interface. The top layer holds the file system, the shell, and the user commands. Those three names are also the directory names in the repository, so the layout is the architecture. Two structures declared in a single header file specify the interface between the layers, which means the boundary a student has to understand to read anything else is written down in one place, and everything above it is written against those declarations rather than against the hardware.

It builds for an emulator or for one of four boards

The running instructions point at a usage file in the repository and at the RISC-V instruction set manuals for the privileged architecture, which tells you both how to start it and what you will need to understand first. The build targets an emulator by default, a 32-bit RISC-V system emulator, and the makefile accepts a board variable that can be set to one of four named boards, with a small development board as the default. Those four are two variants of one art board, a smaller variant of another, and a twenty thousand design. For a course this matters more than it would for a product: the difference between running under an emulator and running on real silicon is the difference between a kernel you can step through and one you can only watch, and the fact that four boards are named suggests the porting work is expected rather than exceptional.

The kernel links with no standard library

The build flags say more about the teaching goal than any documentation could. The linker is told not to pull in the standard library and is given only the compiler's own runtime support, which means there is no C library underneath the kernel to hide behind. Include paths point at five separate subdirectories of the shared library tree, one per facility, so the kernel's dependencies are visible as directories. The instruction set and ABI are named explicitly, along with the privileged extension for control and status registers, and section garbage collection is enabled at both compile and link time so unused code disappears from the image. A custom linker script defines the final layout, which is the file a reader should open if they want to understand where the kernel actually lives in memory.

The build dumps a listing so you can read the binary

One build step is worth singling out because it is unusual for a small project and perfectly suited to this one. After the kernel is linked, the makefile runs a disassembler over the output and writes a listing into the debug directory, with flags requesting source interleaving, all headers, demangled names, line numbers, and wide output. In other words, the build produces a file you can read top to bottom, showing the machine code next to the C that produced it, with file and line information attached. For a teaching system whose stated purpose is that a student read all the code, generating the readable form as part of the normal build is the right default, and it is also how you check the linker script did what you expected.

Two toolchains chosen by a single variable

Getting the cross-compiler is the one piece of setup the readme pushes onto you, and the makefile offers two ways. Setting a variable selects the official GNU toolchain for RISC-V, whose tools carry one target triple, and leaving it unset uses prebuilt binaries from a different distribution, whose tools carry another. Everything else in the makefile follows from that choice, because the compiler, disassembler, and copier variables are all set in the same branch. It is a small piece of conditional logic with a large practical consequence: a first-time builder who does not know which triple their toolchain uses can waste an evening on linker errors that are really toolchain mismatches. Reading the top twenty lines of the makefile before installing anything saves that.

Courses, ports, and a game that runs on it

The acknowledgements are unusually informative about what the project is for. The book that accompanies it contains nine course projects built on the system, and two of the people thanked provided feedback on that book while using the system in their own courses, at one university in the spring and another with two course numbers listed. Two ports are credited: one to a simple processor written in a hardware description language, and one to an embedded board and a compute module, which shows the abstraction layers are real rather than decorative. Someone also made a first-person shooter run on it, and someone else made a video introducing the project. The licensing header in the build file names a university and a year, which is the last thing to check before you reuse any of it.

Editorial conclusion

This project fits a course on operating systems, or a reader who wants a whole system in one sitting rather than a subsystem from a large one. Two things to know before you start. The line count is a measurement produced by a counting tool with markdown excluded, so treat it as a scale indicator rather than an exact figure. And the build targets a specific instruction set and ABI with a custom linker script, which means you will be installing a cross-compiler and reading a link command rather than typing a familiar one-liner.

Frequently asked questions

What is egos-2000?

A teaching operating system of roughly two thousand lines that implements the components of a small operating system and runs both under a RISC-V emulator and on real boards. Its stated goal is that every student can read all of the code, and a companion book contains nine course projects built on it.

How large is the egos-2000 codebase?

About two thousand lines, and the readme shows the count rather than asserting it: roughly sixteen hundred lines of C across thirty files plus a couple of hundred in headers, with markdown excluded and comments and blank lines counted separately.

What are the layers in egos-2000?

Three, named after the metaphor the project is built on: a hardware layer with terminal, disk, timer, and memory interfaces, a hardware-independent layer with the process control block and the system call interface, and an application layer with the file system, shell, and user commands. The directory names match the layer names.

Which boards can egos-2000 be built for?

The makefile accepts a board variable naming four options, with a small development board as the default, and it also builds for a 32-bit RISC-V emulator. The kernel links without a standard library, uses a custom linker script, and the build emits a disassembled listing with source interleaved.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. yhzhang0128/egos-2000 on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/yhzhang0128-egos-2000.svg)](https://hysenlabs.com/projects/yhzhang0128-egos-2000)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/yhzhang0128-egos-2000.svg)](https://hysenlabs.com/projects/yhzhang0128-egos-2000)

Was this useful?