Operating System in 1,000 Lines – Intro
128 comments
·January 8, 2025nuta
sesm
> Designing an OS is like creating your own world
Or like building your temple so you can talk to God directly
6510
We won't know until we try.
pronoiac
If you want PRs, I suggest you set up Semantic Linefeeds* sooner, rather than later. Each sentence gets its own line, and it really helps avoid merge conflicts.
* https://rhodesmill.org/brandon/2012/one-sentence-per-line/
johndoe0815
Are you planning to also provide an English translation of your microkernel book? That sounds very interesting...
nuta
Unfortunately not. Maybe I'll write another online book like this in English, after building a more practical microkernel-based OS. It's a very interesting topic indeed :D
Rochus
Right, that would be great.
jb_briant
"Designing an OS is like creating your own world"
Making video game is also like creating your own world!
And it's order of magnitude less hard than making an OS...
Bonus point, you have a chance to make a living from it!
leonewton253
actually making a video game would be 100x more complicated. Plus kernel developer jobs are more lucrative than most game dev jobs.
jb_briant
Is it really more complicated to make a video game that a kernel? I don't consider myself knowledgeable enough to make a full kernel by myself but I did manage to make a full 3d video game by myself.
Also I'm not speaking about making a game engine along with the game.
Having a kernel dev job is different than making your own kernel, speaking on a "world builder" perspective.
niutech
How does your book compare with the classic "Operating systems design and implementation" by Andrew S. Tanenbaum and Albert S. Woodhull implementing MINIX?
nuta
I thinks this 1,000 OS book is a good start for beginners before diving into the MINIX book.
MINIX book describes more practical designs, with a more feature-rich implementation. However, UNIX features such fork, brk, and tty are not intuitive for beginners. By writing a toy OS first, readers can compare the toy OS with MINIX, and understand that UNIX-like is just one of many possible designs. That's an important perspective IMO.
Also, readers can actually implement better algorithms described in the MINIX book. It makes the MINIX book more interesting to read.
LeFantome
This is so much easier. You are implementing printf on page 5 and it can handle formatted output to the screen for integers, hexadecimals, and strings. Minix eventually gets around to the write system call but even then it is actually just a way of sending bytes from a buffer to a file descriptor. To a what? That is a lot more complexity for, in some ways, less functionality. For write, you still have to write printf on top.
The Tanenbaum book is great but it is a particle physics textbook compered to this OS cookbook.
viraj_shah
Hi OP, this looks super cool. I remember hearing about this (https://www.linuxfromscratch.org/) many years ago but have never done it.
Curious, what are the prerequisites for this? Do I have to know about how kernels work? How memory management, protection rings or processes are queued? Some I'd like to definitely learn about.
johnmaguire
LFS is about building a Linux distribution from scratch (i.e. using the Linux kernel.)
The book in question is about how to build your own operating system (i.e. a non-Linux) kernel from scratch.
> We'll implement basic context switching, paging, user mode, a command-line shell, a disk device driver, and file read/write operations in C. Sounds like a lot, however, it's only 1,000 lines of code!
nuta
Thank you! If you've written some programs (ideally in C), you're good to go. You might stuck on some concepts, but you can learn one by one. IMO, implementing it makes you to understand the concepts more deeply, and learn more that you won't notice when you just read textbooks.
Also, because the implementation in this book is very naive, it would stimulate your curiosity.
null
laurieg
Great resource, thanks for sharing.
I thought the written text was very high quality and didn't show many of the usual tells of a non-native writer. Could you share some details of how you used AI tools to help write it?
nuta
Copy-and-pasting to ChatGPT. Machine translation (JP to EN) before this LLM era was already high quality, but LLM does a really great job. It does not translate as is, but understands the context, drops unnecessary expressions (important!), and outputs a more natural translation.
That said, LLM is ofc not perfect, especially when the original text (or Japanese itself) is ambiguous. So I've heavily modified the text too. That's why there are some typos :cry:
sydbarrett74
Did you post to OSDev?
exDM69
Very delightful article. Based on my experience in "hobby" OS programming, I would add setting up GDB debugging as early as possible. It was a great help in my projects and an improvement over debugging with the QEMU monitor only.
QEMU contains a built-in GDB server, you'll need a GDB client built for the target architecture (riscv in this case) and connecting to the QEMU GDB server over the network.
quruquru
Agree, and I'll add 3 other really useful QEMU features for osdev:
1) Record & Replay: Record an execution and replay it back. You can even attach GDB while replaying, and go back in time while debugging with "reverse-next" and "reverse-continue": https://qemu-project.gitlab.io/qemu/system/replay.html
2) The QEMU monitor, especially the "gva2gpa" and "xp" commands which are very useful to debug stuff with virtual memory
3) "-d mmu,cpu_reset,guest_errors,unimp": Basically causes QEMU to log when your code does something wrong. Also check "trace:help", there's a bunch of useful stuff to debug drivers
kotborealis
Record & replay sounds really nice, but the actual reverse-debugging is broken, see https://gitlab.com/qemu-project/qemu/-/issues/2634
jannesan
thanks for sharing! qemu is very powerful, but it’s hard to discocer a lot of these features
o11c
> you'll need a GDB client built for the target architecture
Thankfully, GDB has a multiarch build these days which should work for all well-behaved targets in a single build.
(the place it is known to fail is for badly-behaved (embedded?) targets where there are configuration differences but no way to identify them)
ramon156
For any rust enthusiasts, phil-opp's guide is such a fun exercise to try out. It was actually the first thing I tried in Rust (very silly idea) and ended up only understanding ~5% of what I had just typed out.
I tried it again 2-3 years later and took the time to go over each subject. I even planned in advance to make sure I was going to finish it.
12345hn6789
It's good but unfortunately he is no longer publishing any further entries. It has been 4 years since the last chapter.
khaledh
Very cool to see someone tackling a small OS for RISC-V.
Shameless plug: I've written hobby OS (well, a kernel actually) in Nim for x86-64[0] and it's all documented as well. I put its development on hold until I create a JetBrains plugin for Nim (in heavy development right now).
elvis70
And discussed here a few months ago: https://news.ycombinator.com/item?id=40962767 - Fusion – A hobby OS implemented in Nim (110 comments)
agentkilo
Very cool! I just started to dvelve into RISC-V, and the book I'm reading (not in English) offers their own emulator[1], which, at a glance, is much simpler than QEMU, and comes with a weird license[2]. I wonder if people actually used it, since it looks like an academic project. Maybe I can also follow this tutorial and test it out.
[1] https://github.com/NJU-ProjectN/nemu/tree/master
[2] https://github.com/NJU-ProjectN/nemu/blob/master/LICENSE
Edit: wrong link
corank
It likely doesn't have performance that's good enough for production use. Doesn't look like there's JIT so it's all instruction by instruction interpreting.
markus_zhang
You can follow the MIT course and use QEMU if so wish.
globular-toast
I started a toy OS years ago based on the book Operating System Design by Douglas Comer. Personally I just couldn't get excited about anything that didn't run on real hardware, so I made mine for Raspberry Pi.
Is there any real hardware that this could run on?
Looking through this seems to use a lot of assembly. In the above the amount of assembly is kept to a minimum. Pretty much just bootstrapping and context switching. The rest is done in C.
johndoe0815
Comer was also my introduction to OS design and I still like the approach used in his Xinu books.
I had a quick glance at the OS in the linked article. This seems to be based on a 32-bit RISC-V with MMU. However, AFAIK, all available RISC-V SoCs with MMU are 64-bit. The 32-bit cores are only used for embedded controllers (unless you want to start designing an FPGA-based system).
The 32 and 64 bit versions of RISC-V are _not_ binary compatible, but the differences are rather small. Porting the MMU code from 64 to 32 bit or the other way round is not very complex, see my RV32 port of xv6 at https://github.com/michaelengel/xv6-rv32 (the regular MIT xv6 version only supports RV64).
The major difference is that virtual address translation on RV32, sv32, uses a two-level page table (10 bit index for the first level, 10 bit index for the second and 12 bit offset) whereas there are several modes of translation for RV64. The most common one, sv39, uses 39 bits of the virtual address split into three 9-bit indexes (so you need a three-level page table for 4 kB pages) plus 12 bit offset.
If you make the modifications, running the OS on real hardware should not be too difficult. The Allwinner D1 is a relatively simply RV64 single code SoC (boards can be found for $20 upwards from aliexpress) and getting the CPU and a UART to work is not that difficult. You can check out my xv6 port to the D1 as a reference: https://github.com/michaelengel/xv6-d1
cess11
That's encouraging, thanks for sharing.
DrNosferatu
I guess this could run on the Raspberry Pico - RP2040 / RP2350.
sschmitt
Cool! Will be interesting to compare to https://github.com/mit-pdos/xv6-riscv!
Shameless plug for my html version of the xv6 book: https://xv6-guide.github.io/xv6-riscv-book/
pshirshov
xv6-riscv is 7000+ LoC. Half of that is userland utilities though.
unwind
Very nice, I always enjoy some low-level discussion like this.
I found a small typo/editing glitch on the "RISC-V 101 page" [1]:
- It's a trending CPU ("Instruction Set Architecture") recent years.
It should probably say "ISA" instead of "CPU", and the word "in" is missing from after the parentheses, right?
Edit: Markdown, don't format the quote as code. Oops.
1: https://operating-system-in-1000-lines.vercel.app/en/02-asse...
nuta
So do I :D
I was wondering that too. I'll update it with other examples (x86 and Arm).
davidw
> The tricky part of creating your own OS is debugging.
The older I get, the more I think I can figure out most problems that don't require some really gnarly domain expertise if I have a good way to iterate on them: code something, try it, see the results, see how they compare with what I wanted. It's when pieces of that are difficult or impossible, or very slow, things get more difficult.
vanderZwan
This looks nice! I would love to have an ebook version to read on my ereader. I wonder how much effort it would take to use the markdown files in the GH repo and convert those.
cheeseface
You can clone the repo and install pandoc. Then run "pandoc index.md *.md -o operating-system-in-1000-lines.epub" in "website/en/" folder and you will have a fully working ebook.
pronoiac
I made:
* an issue, "make an ebook": https://github.com/nuta/operating-system-in-1000-lines/issue...
* an epub: https://github.com/pronoiac/operating-system-in-1000-lines/r... The epub is mostly ok but a bit broken.
vanderZwan
Thank you for the tip!
ChrisMarshallNY
I never counted, but my first professional software project was an operating system (firmware) for an RF switching box. It was written in 8085 ASM, and was probably in the neighborhood of 1,000 lines.
Apples to oranges, though. It was a specialized firmware system. Probably the biggest part was the IEEE-488 communications handler.
ChrisMarshallNY
This is it[0].
Looks like more like 2800 lines.
[0] https://littlegreenviper.com/wp-content/uploads/2022/07/TF30...
pm2222
Two projects mentioned by this one:
https://github.com/nuta/microkernel-book/
https://github.com/mit-pdos/xv6-riscv
Author here.
I wrote this book so you can spend a boring weekend writing an operating system from scratch. You don’t have to write it in C - you can use your favorite programming language, like Rust or Zig.
I intentionally made it not UNIX-like and kept only the essential parts. Thinking about how the OS differs from Linux or Windows can also be fun. Designing an OS is like creating your own world—you can make it however you like!
BTW, you might notice some paragraphs feel machine-translated because, to some extent, they are. If you have some time to spare, please send me a PR. The content is written in plain Markdown [1].
Hope you enjoy :)
[1] https://github.com/nuta/operating-system-in-1000-lines/tree/...