From 32070e9af4f292e1ddc49f9f1643bd7e8689192c Mon Sep 17 00:00:00 2001
From: Mark <mark@betalupi.com>
Date: Sun, 2 Mar 2025 21:00:16 -0800
Subject: [PATCH] Write README

---
 README.md | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f72fba1..0b0b32b 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,36 @@
-- fix asm loader
-- document everything
\ No newline at end of file
+# TetrOS: bare-metal tetris
+
+## TODO:
+- Fix stage 1 loader
+
+## Features
+- Compiles to a standalone disk image
+- Written from scratch using only Nasm and Rust
+- Custom BIOS bootloader
+- 32-bit x86 OS
+- 🌟 Detailed comments. Read the [makefile](./Makefile), then start in [`./bios/main.asm`](./bios/main.asm).
+
+
+## Non-Features
+- Never tested on real hardware
+- Minimal gameplay and graphics. These features aren't hard to implement, but also don't present any interesting challenges. I have other things to do.
+
+
+## 🚀 Building and Running
+- All scripts are in the [makefile](./Makefile).
+- To build and run, use `make qemu`.
+  - Dependencies: `nasm`, `cargo`, GNU `binutils`, `qemu`
+  - This will NOT work on MacOS. BSD `ld` does not work like GNU `ld`.
+- Alternatively, a compiled disk image for the latest commit is [here](https://git.betalupi.com/api/packages/Mark/generic/tetros/latest/disk.img). This is the same file produced by `make`.
+  - Download it and run `qemu-system-i386 -d cpu_reset -no-reboot -smp 1 -m 2048 -machine q35 -net none -serial stdio -fda "disk.img"`
+
+
+## 📜 Resources
+**Used directly:**
+- [jdh's video](https://www.youtube.com/watch?v=FaILnmUYS_U)
+- [The OSDev wiki](https://wiki.osdev.org/Main_Page)
+- [RedoxOS bootloader](https://gitlab.redox-os.org/redox-os/bootloader)
+
+**Useful background knowledge:**
+- [Writing an OS in Rust](https://os.phil-opp.com)
+- [Operating Systems: From 0 to 1](https://github.com/tuhdo/os01)
\ No newline at end of file