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

Keira is a freestanding, multi-language x86_64 operating system kernel. It
manages system hardware resources, coordinates low-level C drivers, and
provides a preemptive priority multitasking scheduler, 44 system calls,
AHCI SATA storage driver, VBE High-Resolution Linear Framebuffer Driver, USB Host Controller Subsystem, Loadable Kernel Modules (LKM), HPET Timer, PCIe ECAM/MSI, io_uring Async I/O, NX/KASLR Protection, Futex Threading, cgroups / PID Namespaces, Native EXT4 Driver, KVM Hypervisor, TPM 2.0 Enclave, BPF Packet Engine, DMA Allocator, Syslog Ring Buffer,
Native TLS 1.3 Cryptographic Engine, IPC Shared Memory & Pipe subsystems, Multi-User Accounts & Hostname, POSIX File Permissions & Multi-TTY, Userland Socket API,
49 native shell commands, and a system shell controlled by a core Rust kernel static library.

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

* Get the latest code: https://github.com/mrvlous/keira
* Setup the workspace: See docs/contributing/setup.md
* Build & run the kernel: `make run`

Architecture & Documentation Map
--------------------------------

Explore the kernel's core subsystems and design details:

* Memory Management: docs/architecture/memory.md
* Task Scheduler: docs/architecture/scheduler.md
* System Calls and Privilege: docs/architecture/syscalls.md
* Cryptographic Subsystem: docs/architecture/crypto.md
* LKM, HPET & SMP Subsystems: docs/architecture/lkm_hpet_smp.md
* PCIe, io_uring & NX/KASLR Subsystems: docs/architecture/pcie_iouring_nx.md
* Futex, Threading & cgroups Subsystems: docs/architecture/futex_cgroups.md
* Hardware Virtualization Hypervisor (KVM): docs/architecture/kvm.md
* Hardware Security TPM 2.0 Enclave: docs/architecture/tpm.md
* Zero-Copy BPF Packet Filter Engine: docs/architecture/bpf.md
* DMA Scatter-Gather Allocator: docs/architecture/dma.md
* Kernel Event Logging & Syslog: docs/architecture/klog.md
* Native EXT4 Linux Filesystem Driver: docs/filesystems/ext4.md

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


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

Find your role below:

* New Kernel Developer - Getting started with kernel development
* Academic Researcher - Studying kernel internals and architecture
* Device Driver Developer - Writing drivers for hardware interfaces
* AI Coding Assistant - LLMs and AI-powered development tools


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

New Kernel Developer
--------------------

Welcome! Start your Keira development journey here:

* Getting Started: docs/contributing/setup.md
* Build Pipeline: docs/contributing/build.md
* Coding Style: docs/contributing/style.md
* Bootstrapping Sequence: docs/architecture/bootstrapping.md

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

Explore the kernel's core subsystems and design details:

* Memory Management: docs/architecture/memory.md
* Task Scheduler: docs/architecture/scheduler.md
* System Calls and Privilege: docs/architecture/syscalls.md
* Cryptographic Subsystem: docs/architecture/crypto.md
* LKM, HPET & SMP Subsystems: docs/architecture/lkm_hpet_smp.md
* Virtual Filesystem (VFS) Layer: docs/filesystems/vfs.md
* FAT Filesystem Implementation: docs/filesystems/fat.md
* TAR Boot initrd Reader: docs/filesystems/tar.md
* Multi-User Accounts & System Hostname: docs/userland/users_hostname.md
* POSIX File Permissions, Redirection & Multi-TTY: docs/userland/tty_permissions.md

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

Write and support hardware device drivers:

* VGA Text Console, Code Editor & VBE Framebuffer: docs/drivers/vga.md
* Serial UART COM1: docs/drivers/serial.md
* Sound (PC Speaker & HDA): docs/drivers/sound.md
* Mouse & CMOS RTC: docs/drivers/mouse_rtc.md
* Intel e1000 Network Driver: docs/drivers/network.md
* USB Host Controller Driver: docs/drivers/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/style.md


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

* Repository Home: https://github.com/mrvlous/keira
* Issue Tracker: https://github.com/mrvlous/keira/issues
* Technical Index: docs/README.md