Keira Kernel
============

Keira is an educational, exploratory freestanding kernel in
Ring 0 built from scratch in safe Rust, Assembly, and C, supporting both modern
64-bit (x86_64) and pure 32-bit (i686) bare-metal architectures.

Built as an open systems programming learning journey, Keira manages hardware
resources from first principles, coordinates modular device drivers, and
provides a preemptive multitasking scheduler, multi-core Symmetric
Multiprocessing (SMP) with 16-bit real-mode AP bootstrap trampolines, POSIX
system calls, bare-metal TCP/IP stack, FAT12/16/32 and EXT4 filesystems, USTAR
initrd, Ring 3 userland isolation with 42 verified ABI security test vectors,
bare-metal io_uring asynchronous I/O engine, High-Precision Event Timer
(HPET) monotonic clocks, and an in-kernel C compiler (kcc.elf).

The Story & Learning Journey
----------------------------

Keira serves as a hands-on laboratory for understanding the core foundations
of computer systems:

* Bare-Metal Bootstrap: Multiboot2, GDT, TSS, IDT, and APIC interrupts.
* Multi-Core SMP: 16-bit real-mode AP bootstrap trampoline (0x8000), Local APIC INIT-SIPI-SIPI wake sequence, ACPI MADT hardware discovery, per-CPU stacks, and race-free swapgs syscall re-entrancy.
* Memory Architecture: Frame bitmapped allocator, 4-level paging, and heap.
* Multitasking: Preemptive timer-tick context switching and POSIX signals.
* Bare-Metal Networking: e1000/RTL8139, ARP, IPv4, UDP, DHCP, DNS, TCP, TLS.
* Storage & Filesystems: ATA, AHCI, NVMe, FAT16, block LRU cache, and VFS.
* Asynchronous I/O: Bare-metal io_uring submission/completion queue engine.
* Kernel Control Plane: Interactive Ring 0 diagnostic shell, hardware telemetry, and VFS management.

Read the detailed engineering journal: docs/journey/README.md

Quick Start
-----------

* Official Landing Page: https://mrvlous.github.io/keira/
* Get the latest code: https://github.com/mrvlous/keira
* Setup the workspace: See docs/contributing/guides/setup.md
* Build & run 64-bit kernel: `make run` (or `make run-64`)
* Build & run 32-bit kernel: `make ARCH=i686 run` (or `make run-32`)
* Build & run with multi-core SMP: `make run SMP=4`
* Build all architectures: `make full`
* Automated multi-architecture test suite: `make test-all`

Hyper-Modular Documentation Architecture
----------------------------------------

Explore the kernel across 13 first-class hyper-modular domains:

* Learning Journey: docs/journey/README.md
* Kernel Core: docs/kernel/README.md
* Memory Subsystems: docs/memory/README.md
* Task & Scheduling: docs/task/README.md
* System Calls: docs/syscall/README.md
* Inter-Process Communication: docs/ipc/README.md
* Filesystems & VFS: docs/fs/README.md
* Hardware Device Drivers: docs/drivers/README.md
* Layered Network Stack: docs/net/README.md
* Cryptographic Security: docs/crypto/README.md
* Shell & Utilities: docs/shell/README.md
* Userland & C SDK: docs/userland/README.md
* Contributor Guidelines: docs/contributing/README.md

More modular guides can be found starting from the documentation map: docs/README.md

Who Are You?
============

Find your role below:

* Systems Student & Learner - Exploring low-level kernel internals from scratch
* Academic Researcher - Studying kernel architecture and Rust safety contracts
* Device Driver Developer - Writing drivers for hardware and block interfaces
* AI Coding Assistant - LLMs and AI-powered development tools

For Specific Users
==================

Systems Student & Learner
-------------------------

Welcome! Start your systems development journey here:

* Learning Journal: docs/journey/README.md
* Getting Started: docs/contributing/guides/setup.md
* Build Pipeline: docs/contributing/guides/build.md
* Coding Style: docs/contributing/guides/style.md
* Contribution Workflow: docs/contributing/guides/workflow.md
* Bootstrapping Sequence: docs/kernel/boot/README.md

Academic Researcher
-------------------

Explore the kernel's core subsystems and design details:

* Memory Management: docs/memory/README.md
* Task Scheduler: docs/task/scheduler/README.md
* System Calls and Privilege: docs/syscall/table/README.md
* Cryptographic Subsystem: docs/crypto/README.md
* Virtual Filesystem (VFS) Layer: docs/fs/README.md
* Process Information Pseudo-Filesystem (ProcFS): docs/fs/proc/README.md
* Virtual Device Filesystem (DevFS): docs/fs/dev/README.md
* FAT Filesystem Implementation: docs/fs/fat/README.md
* TAR Boot initrd Reader: docs/fs/storage/tar_initrd.md
* Native KCC Compiler: docs/userland/compiler/README.md
* Freestanding POSIX C Library: docs/userland/libc/README.md
* Epoll Event Multiplexer: docs/ipc/event/epoll.md
* Asynchronous I/O (io_uring): docs/ipc/uring/README.md
* Logical Volume Manager & RAID: docs/fs/storage/lvm_raid.md
* Kernel Privilege & Sandbox Security: docs/userland/system/users.md
* VFS Modes & Boundaries: docs/userland/system/permissions.md
* System Hostname Configuration: docs/userland/system/hostname.md

Device Driver Developer
-----------------------

Write and support hardware device drivers:

* Driver Framework: docs/drivers/README.md
* VGA Text Console & VBE Framebuffer: docs/drivers/display/README.md
* Serial UART COM1: docs/drivers/serial/README.md
* Storage (IDE, AHCI, NVMe): docs/drivers/storage/README.md
* Intel e1000 Network Driver: docs/net/driver/e1000.md
* USB Host Controller Driver: docs/drivers/bus/usb.md

AI Coding Assistant
-------------------

CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and
follow the coding standards before proposing changes to Keira:

* Coding Style and Comment Rules: docs/contributing/guides/style.md

Communication and Support
=========================

* Project Landing Page & Live Tour: https://mrvlous.github.io/keira/
* Repository Home: https://github.com/mrvlous/keira
* Issue Tracker: https://github.com/mrvlous/keira/issues
* Technical Index: docs/README.md
* Project Credits & Acknowledgements: CREDITS