+<p align="center">
+ <a href="docs/README.cn.md">简体中文</a> | <a href="#the-lunaixos-project">English</a>
+</p>
+
+# The Lunaix Project
+
+The Lunaix kernel (or soon-to-be LunaixOS) is a hobby kernel, started in 2022,
+written entirely from scratch. With a big ambition of being POSIX-compliance,
+and designed with performance and modernity in mind, with some independent
+thoughts being applied in architectural design.
+
+
+This project is built entirely from first principles - meaning no code was
+copy-pasted or recycled from other OS projects or tutorials. Lunaix didn't begin
+as an attempt to outperform anything; it started as a personal challenge to
+learn OS theory and explore advanced kernel features through original design
+and implementation. Everything you see here was developed solo, part-time,
+with only hardware specs and my beloved **Modern Operating Systems** as guidance.
+
+If you're a kernel hobbyist looking for a fresh take or tired of mass-produced, tutorial-style
+projects, then welcome, you're in the right place!
+
+
+|  |
+|:--:|
+| *Lunaix over serial* (`console=/dev/ttyS0`) |
+
+|  |
+|:--:|
+| *Lunaix over VGA text mode* (`console=/dev/ttyVCON0`) |
+
+> By the way, do you know there is an online video course by the author on the design of lunaix? [Check it out](https://space.bilibili.com/12995787/channel/collectiondetail?sid=196337) (although it is in Chinese!)
+
+## Features
+
+Lunaix is a multi-architecture, general-purpose kernel built with performance,
+modularity, and robustness in mind. Its design emphasizes advanced abstractions,
+proactive error detection, and subsystem isolation. Lunaix is
+
++ **Fully-preemptive** for responsive multi-tasking
++ **Modular** with compile-time configurable components and extensible
+ subsystems
++ **High-performance**, leveraging modern caching strategies and efficient
+ infrastructures.
++ **Fault-tolerant**, with built-in error handling and stack backtracing
++ **Robust by design**, using mechanisms like proactive deadlock detection
+ and driver isolation
+
+A significant amount of effort has gone into crafting clean abstractions,
+implementing advanced kernel features, and applying performance optimizations
+throughout the system.
+
+To better illustrate the scope of work already done, the following non-exhaustive
+list outlines currently supported features in Lunaix:
+
+### List of All Features
+<details>
+
+<summary>Click to Expand</summary>
+
++ Multi-ISA
+ + x86_32
+ + x86_64
+ + Aarch64 (WIP)
++ Boot protocol
+ + abstraction for different protocol
+ + configurable kernel boot-time parameters
++ Platform resource management and definition
+ + read-only ACPI table interpretation
+ + full devicetree implementation
++ Memory management
+ + architecture-neutral abstraction
+ + highmem
+ + copy-on-write
+ + page sharing
+ + explicit huge page
+ + on-demand paging
+ + compound page
+ + reverse mapping (rmap)
+ + memory compaction (WIP)
+ + slab-style object allocator
+ + inter-process address space access
++ Multi-tasking
+ + fully preemptive
+ + protection levels
+ + process isolation
+ + native threading
+ + signal mechanism
+ + round-robin scheduler (for now)
+ + kernel level multi-tasking (i.e. kernel threads)
+ + taskfs: file system interface to process and threads
++ File system
+ + POSIX-compliant interface
+ + virtual file system framework
+ + file system mounting mechanism
+ + page cache for file IO
+ + inode/dnode caching
+ + ext2 (rev.0, rev.1)
+ + iso9660 (rock-ridge)
+ + twifs: kernel state fs interface.
++ Device management and interrupt handling
+ + unified IRQ framework
+ + unified driver framework for heterogenous devices
+ + modular driver model allow compiled-time toggling
+ + asynchronous operation model supported
+ + devfs: device fs interface.
++ Block I/O (blkio)
+ + unified block IO interface
+ + IO request packets caching
+ + asynchronous IO operation
++ Serial I/O
+ + POSIX-compliant serial IO model
++ Caching Infrastructure
+ + LRU replacement policy and pooling
+ + kernel daemon for dynamic and transparent cache managements
++ Error handling and detection
+ + stack backtracing with symbol resolution
+ + stack unwinding for nested exception
+ + CPU state dumping
+ + deadlock/hung-up detection
+
+</details>
+
+### List of Built-in Drivers
+
+<details>
+
+<summary>Click to Expand</summary>
+
++ Architecture Neutral
+ + UART 16650-compatible driver
+ + Serial ATA AHCI
+ + PCI 3.0
+ + PCIe 1.1
+ + Standard VGA
++ Intel x86
+ + RTC (Intel PCH)
+ + IOAPIC IRQ controller
+ + APIC Timer
+ + Legacy i8042 keyboard controller
++ ARM
+ + GICv3
+ + PL011 (WIP)
+</details>
+
+## Documentations
+
+There are documentations avaliable if you want to dig deeper. Keep in mind they are still work in progress and missing localisation.
+
++ [Luna's Tour - Into Lunaix's Inner Workings](docs/lunaix-internal.md)
++ [Syscall Number Assignments](docs/lunaix-syscall-table.md)
+
+## Compile and Build
+
+Building lunaix is simple, no more bloated dependencies to install, basic
+`build-essentials` installation plus a python are sufficient.
+
++ gcc (recommend v12+)
++ binutils
++ make
++ python (recommend v3.11+)
+
+And also one should have environment variable `ARCH=<arch>` exported, where
+`<arch>` is one of the supported arhcitecture (`x86_32`, `x86_64`, `aarch64`).
+
+For cross compilation, also export `CX_PREFIX` to the gcc prefix for the
+corresponding `<arch>`.
+
+The following `make` actions are then available to use.
+
+| Make command | Usage |
+| ---- | ---- |
+| `make all` | Build the kernel bin |
+| `make rootfs` | Build the stock rootfs |
+| `make clean` | clean |
+| `make config` | run configuration tool |
+| `make reconfig` | revert to default and restart configuration |
+
+A successful build will give `build/bin/kernel.bin`.
+
+> Please note: this is the kernel, not a bootable image, it require a bootloader
+> to boot and specify the rootfs.
+
+## Get Started
+
+If you are impatient, or just want something to run and don't want to went
+through tedious process of configuring rootfs and tweak kernel parameters. You
+can use the `live_debug.sh` provided in the lunaix root directory to quickly
+bring up the system with default parameters (also used by the author for
+debugging).
+
+### Quick Start
+
+This will get you up and running real quick. We will use `x86_64` as example.
+
+Assuming a Linux or other Unix-like shell environment. We also expect you to be able to sort out trivial issues like missing packages.
+
+**Select your target**
+```sh
+$ export ARCH=x86_64
+```
+
+**Check Python**
+```sh
+$ python --version
+```
+
+Ensure at least `3.11`
+
+**Check compiler**
+```sh
+$ gcc -dumpmachine
+```
+
+Ensure `x86_64-linux-gnu` or anything resemble `x86_64`
+
+**Check QEMU**
+```sh
+$ which qemu-system-x86_64
+```
git://scm.lunaixsky.com / lunaix-os.git / blobdiff