From cd8d3f3363e19eb34a75b13c04ccb796592c2967 Mon Sep 17 00:00:00 2001
From: Mark Poliakov <mark@alnyan.me>
Date: Fri, 8 Dec 2023 17:51:21 +0200
Subject: [PATCH] doc: add a README

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..6706bf0b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+yggdrasil-kernel
+================
+
+Rust Unix-like operating system kernel.
+
+See also:
+
+* [ABI for kernel-user communication](https://git.alnyan.me/yggdrasil-abi)
+* [Rust fork to use with the kernel](https://git.alnyan.me/yggdrasil/yggdrasil-rust)
+* [Userspace programs](https://git.alnyan.me/yggdrasil/yggdrasil-userspace)
+* [yboot — x86-64 UEFI bootloader](https://git.alnyan.me/yggdrasil/yboot)
+
+Main features
+-------------
+
+* Architecture support: [aarch64](/src/arch/aarch64) and [x86_64](/src/arch/x86_64)
+* Kernel/userspace preemptive multithreading
+* Kernel-space multitasking with `async`/`await` runtime
+* Symmetric Multiprocessing
+* Unix-like virtual filesystem:
+	files, directories, block/char devices, symlinks, mounts
+* In-memory read-write filesystem for tar-based initrd
+* sysfs/devfs
+* Binary formats: ELF + `#!/...` shebangs
+* Rust-style interfaces for most of the stuff like memory management, devices etc.
+
+aarch64-specific:
+
+* PSCI for SMP start-up and power control
+* PL011 serial port
+* ARM generic timer as system/monotonic timer
+* GICv2 IRQ controller
+
+x86_64-specific:
+
+* UEFI boot through [yboot](https://git.alnyan.me/yggdrasil/yboot) 
+	(no plans for legacy boot)
+* PCIe, with plans to extend to aarch64 as well
+* I/O and Local APIC IRQ controllers
+* PS/2 keyboard, 
+* i8253-based timer (got some problems with HPET on 
+	real hw, had to revert, lol)
+* COM ports
+* ACPI, [work in progress](https://github.com/rust-osdev/acpi), mostly broken
+	on real hardware
+	* ACPI shutdown
+	* PCI IRQ pin routing
+	* Events like power button, etc.
+* Fancy framebuffer console
+
+Userspace features:
+
+* Sanitized system calls better suited for Rust
+* Userspace threads
+* Synchronization primitives through futex-like interface
+* Unix-like signals and exceptions
+
+General plans (in no particular order)
+--------------------------------------
+
+* Better unification of architecture code
+* `async` for VFS (?)
+* PCIe NVMe block device
+* PCIe SATA block device
+* PCIe XHCI USB devices
+* Better algorithms for memory management
+
+Navigation
+----------
+
+* `src/arch` — architecture-specific code
+* `src/device` — device driver implementations
+	* `bus` — bus devices like USB, PCIe etc.
+	* `display` — everything related to graphic displays
+	* `power` — power and reset controllers
+	* `serial` — serial transceiver drivers
+	* `devtree.rs` — stuff related to ARM DeviceTree
+	* `tty.rs` — Unix-style terminal driver implementation
+* `src/fs` — in-kernel filesystems (sysfs/devfs)
+* `src/mem` — memory management
+* `src/proc` — process information management
+* `src/syscall` — system call handling
+* `src/task` — kernel and userspace tasks, processes and threads
+* `src/util` — utilities used within the kernel
+* `src/init.rs` — kernel init thread impl.
\ No newline at end of file