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/...
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/
> Designing an OS is like creating your own world
Or like building your temple so you can talk to God directly
We won't know until we try.
TempleOS: https://en.m.wikipedia.org/wiki/TempleOS
"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!
Are you planning to also provide an English translation of your microkernel book? That sounds very interesting...
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?
Nice project, short and concise enough for an undergrad to learn basic os concept and implementation.
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.
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!
How does your book compare with the classic "Operating systems design and implementation" by Andrew S. Tanenbaum and Albert S. Woodhull implementing MINIX?
Did you post to OSDev?
This is fantastic. Thank you so much for writing this.
Excellent content!
Kudos for not being yet another UNIX clone tutorial.
Could you port this to riscv64 please?
Porting to any platform is trivial after understanding the basics as described in these articles
The author explicitly describes why they chose riscv32
Why would you want the author to use riscv64 instead?
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.
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
thanks for sharing! qemu is very powerful, but it’s hard to discocer a lot of these features
> 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)
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.
Hey, any chance you could link it please?
Thank you!
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).
And discussed here a few months ago: https://news.ycombinator.com/item?id=40962767 - Fusion – A hobby OS implemented in Nim (110 comments)
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
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.
You can follow the MIT course and use QEMU if so wish.
Link to the MIT course?
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/
xv6-riscv is 7000+ LoC. Half of that is userland utilities though.
> 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.
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...
So do I :D
I was wondering that too. I'll update it with other examples (x86 and Arm).
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.
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.
Thank you for the tip!
Two projects mentioned by this one:
https://github.com/nuta/microkernel-book/
https://github.com/mit-pdos/xv6-riscvJust a small typo in the RISC-V 101 chapter. It says "it's a trending CPU (ISA) recent years." I believe it should read "in recent years."
Don't hesitate to send the author an email, open a ticket or a PR to make sure they see this, it seems more appropriate than HN comments for this kind of things :-)
https://operating-system-in-1000-lines.vercel.app/en/17-outr...
I'm sure they know that those things were possible. Perhaps you could have done it instead?
They bothered to stop and suggest improvements here. That's enough work for them. They don't need to go elsewhere and do more, any more than you did.
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.
This is it[0].
Looks like more like 2800 lines.
[0] https://littlegreenviper.com/wp-content/uploads/2022/07/TF30...
This is on my to do list of things to learn but I also don't know yet the purpose other than it being your own. Maybe security since most of what I work with is on top of the OS eg. programming languages. Maybe for RTOS applications at any rate this and OS Dev good resources.
I find this kind of thing most useful for microcontrollers and real-time embedded systems that don't require full networking. I've used many of these concepts but maybe not all at once on what many would call "bare metal" systems with no OS. Audio gizmos like cheap synths, LED nodes, things you want booting really fast with well-bounded functionality. An OS can get in the way with this kind of system if all you really need is some timers and simple I/O. You may still want a primitive scheduler, sane interrupt dispatching, and filesystems.
This looks nice. Thank you! Been considering something like that for quite a while now (Since my own risc-v CPU, written in VHDL, is working actually). I might get this as inspiration and rewrite it in Rust (tm) - Because I wnat to learn Rust, too
Good stuff! Saving it for the weekend because I'm such a slow reader!
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.
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
That's encouraging, thanks for sharing.
I guess this could run on the Raspberry Pico - RP2040 / RP2350.
I’m interested in the use of things like virtio instead of real hardware.
Are there other virtualisation-driven designs for hardware devices out there rather than the qemu stuff?
Virtio is not qemu only. For example, the macOS virtualization framework on Apple Silicon Macs (and x86 machines IIRC) also provides virtio devices, other hypervisors.
An overview of the available devices can be found in this presentation:
https://crc.dev/blog/Container%20Plumbing%202023%20-%20vfkit...
you can try plain KVM its a bit more pain to get a system up tho compared to qemu which does a lot for you (--enable-kvm)
I'd love to try implementing this in some other languages.
Ah yes, I have a few (too many as always, but I think that's good, especially when getting older; need to not get complacent) resolutions for 2025, one of them is to write a OS/DB with a development environment. Just to see how far I can take it. So these kind of tutorials are great. I was already going to make it RISC-V first because i'm interested.
This looks great, thank you for making this.
A noble idea, but Github is literally littered with hobbyist home-grown Unix-like kernels in C.
As an industry are we not supposed to be trying to move away from hoary old unsafe C?
Could we not have a hobbyist educational OSes in more of the C replacements?
Drew DeVault wrote Bunnix in Hare, in one month. There's the proof of concept.
How about tiny toy Unix-likes in Zig, Nim, Crystal, Odin, D, Rust, Circle, Carbon, Austral?
How about ones that aren't ostensibly suitable for such tasks, such as Go or Ada?
Yes I know Ada is not a good fit, but there has already been a Unix-like OS entirely implemented in a derivative of Pascal: TUNIS.
https://en.wikipedia.org/wiki/TUNIS
This might need work from skilled expert practitioners first. That's good. That's what experts are for: teaching, and uplifting newbies.
There was a project to do C# on the bare metal.
https://migeel.sk/blog/2023/12/08/building-bare-metal-bootab...
How about a Unix-like in C#? Get the Unix and .NET folks interested in this stuff.
Even if the OS never leads to anything, maybe the tooling might prove useful. I am sure someone somewhere would have uses for bare-metal GoLang.
Saying that, I really don't think we need any more Unix-like OSes. There are far far too many of those already. There is a huge problem space to be explored here, and there used to be fascinating OSes that did things no Unix-like ever did.
OSes that are by modern standards tiny and simple but explored interesting areas of OS design, and are FOSS, with code out there under permissive licenses:
* Plan 9 https://github.com/plan9foundation/plan9
* Inferno https://github.com/inferno-os/inferno-os
* Symbian https://github.com/SymbianSource
* Parhelion HeliOS https://archive.org/details/Heliosukernel
There is already an effort at Plan 9 in Rust:
https://github.com/dancrossnyc/r9
Why not Plan 9 in Zig, or Hare, or even D?
Plan 9 imposes and enforces considerably more simplicity on C as it is: you can't #include stuff that already has #include statements of its own. The result is a compilation speedup of around 3 orders of magnitude. That would be a benefit to the would-be C replacements too, wouldn't it?
> Yes I know Ada is not a good fit, but there has already been a Unix-like OS entirely implemented in a derivative of Pascal: TUNIS.
Isn't it? There is a very well-developed kernel written in ADA with SPARK and formally verified at that: https://ironclad.nongnu.org
And PASCAL-derived languages were very popular for operating systems in the 80s. To name a few: Apple's LISA OS, DEC's VAXELN, and OBERON. There were others as well that didn't quite make it, like DEC's MICA and Acorn's ARX.
Thanks for this!
I did not realise VAXELN was in Pascal. The others I did know of, yes, although Ironclad only from another comment in this thread.
> Yes I know Ada is not a good fit
Why?
> https://en.wikipedia.org/wiki/TUNIS
Interesting; do you know whether the source code is available somewhere?
No, sadly, I don't know of any.
You might ask co-developer Prof James Cordy: https://en.wikipedia.org/wiki/James_Cordy
Or approach the University of Toronto: https://www.utoronto.ca/
I had a look at the available literature. Many of the ideas are pretty similar to the work of Per Brinch Hansen a decade earlier. Actually the successor of Concurrent Euclid, called Object-Oriented Turing, is pretty interesting, because it is still a Pascal descendant, but supports modules, declarations in the statement flow, OO and concurrent programming. As it seems it's worth a closer look.
Dijkstra famously said that programmers who started with BASIC are "mentally mutilated". But I think this applies a lot more to C and UNIX.
Most of them don't seem to understand how anything substantially different could exist in the world of computing - every other language and operating system is seen as either an inferior copy, or as another layer of abstraction building on top of C and UNIX.
> Dijkstra famously said that programmers who started with BASIC are "mentally mutilated"
He knew how to make friends.
To be fair, he was talking about classic BASIC which didn't even have user defined procedures but just goto and gosub similar to jumps and calls in assembly language. I remember when I started learning Pascal after BASIC on the Apple II and there was so much to unlearn about programming because how you wrote BASIC was so different from any other high level programming language.
Sure. Pascal btw. had a pretty "flexible" goto statement, I would say nearly as flexible as BASIC; Apple ][ Pascal was a bit more structured though. In original Pascal, you could use goto to even jump out of a procedure; Apple Pascal could only jump within a procedure, and only if goto was enabled at all, if I remember correctly.
True. And even C has one. I guess you could write "spaghetti code" in Pascal if you really wanted to.
Exactly my own sentiments!
There are very good kernels written in Ada, like Ironclad[1].
Besides, what's the point of this comment? What if people wanted to write a million more Unix-like kernels in C? Do you think this is bad? Why do you care? If you want, just write your own in whatever language you want, with whatever design you want.
> Why not Plan 9 in Zig, or Hare, or even D?
Because nobody to this point was interested in doing this. It's really that simple.
I agree. the GP's comment has a flavour of "people shouldn't like the things I don't like".
"Make your own kernel" is a thing-in-itself, and "runs on <X> hardware/VM" + "provides <Y>-like API for programs" are tangible, concrete goals to aim for, even if you personally don't like the <Y> API or the architectural choices it implies.
To give an analogy: https://www.nand2tetris.org/ is an amazing learning experience, even though games other than Tetris should and do exist
Personally, I like the AROS project, aiming to provide an operating system that implements the AmigaOS APIs and runs on many architectures, but lots of users are interested in running it on 680x0 Amigas and spiritually-related PowerPC devices: https://en.wikipedia.org/wiki/AROS_Research_Operating_System
It's OK for programmers to write a thing just for the learning experience. If it gains adoptees, that's a happy accident.
> There are very good kernels written in Ada, like Ironclad[1].
Interesting. Thanks.
> Besides, what's the point of this comment? What if people wanted to write a million more Unix-like kernels in C? Do you think this is bad? Why do you care?
Because it seems to me that modern OS design is caught in a deep deep rut, and the "OS in 1000 lines" article that we are discussing is digging that rut even deeper.
Don't repeat the mistakes of the past. Make interesting new mistakes. It's more fun.
SPIN in Modula-2: https://www-spin.cs.washington.edu/
Symbian is anything but simple!
:-) Fair point.
Very very small, compared to Android or iOS or any modern Linux, though.
OS’s written in Ada included MaRTE OS (open source), Intel’s BiiN system, and the Army Secure Operating System (ASOS) (IIRC).
The Muen Seperation Kernel (muen.sk) is a secure hypervisor written in SPARK Ada.
Ada was designed for low-level programming. It makes sense it does operating systems fairly easily. Parts of them will break its safety features. They can be validated with external tools, though.
Another trick, used in House with H layer, is to wrap the lowest-level parts which you might do in assembly. Build the GC or whatever, too. Then, everything else is in the higher-level language. These data, the lowest-level portions can be specified, verified, and implemented.
The article nicely explains how to build a minimalist OS — works great as an intro material. I think understanding basic OS concepts is essential for performance tuning and debugging.
Notice a bunch of downvotes -- Apologies for being unfamiliar with the rules here (I've always been reading HN, but I'm new to commenting). I should've added a lot more details to my previous comment and been more specific. Any other guides would be helpful too. I'll be careful in the future.
When I learned OS, I followed MIT 6.828 (https://pdos.csail.mit.edu/6.828/2017/overview.html) and implemented a small OS called JOS based on Xv6. So if you're looking for some teaching OS in x86, check it out.
Someone probably has a python one-liner for it on leetcode
This article brilliantly demonstrates the elegance of simplicity in systems design, proving that even complex concepts like operating systems can be demystified with clarity and minimalism. It's a reminder that understanding fundamentals often unlocks deeper innovation. How might this inspire rethinking other "big" systems?
this comment reads... a lot like chatgpt
It’s just an alt used to promote some guy’s startup. You should look up it’s comments…
All the comments from the account are deleted.
I always use an LLM to recraft my comments to ensure they are clear (English isn't my first language). Is that not allowed here?
HN ostensibly tries to have thoughtful, engaged conversations. LLM grammatical cleanups and translations are absolutely fair game. The comment has certain hallmarks (broad, sweeping summary, certain word choices, ...) suggesting that an LLM had more creative liberty than HN really likes to see -- in sort of an Uncanny Valley situation, it's hard to tell if the LLM produced the post or if a person did (plus, somebody apparently went digging and didn't see a lot of value in your other comments while also finding self-endorsements, which paints this one in a worse light).
You might have better luck with prompts that try to adhere better to your intent:
> English is not my first language. Please correct the spelling/grammar and perhaps teach me up to one idiom that would fit well in the following comment, but leave the meat of the message largely the same.
> Please translate the following [franglish/spanglish/(English mixed with a few words from your native language as appropriate to better convey your point)] to English suitable for a forum post.
I appreciate this response. Thank you
dang clean up on isle 10