> ## Documentation Index
> Fetch the complete documentation index at: https://kernel.mvhcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MVH Kernel Architecture Overview: Layers and Components

> Understand how MVH Kernel is structured: HAL, memory subsystem, VFS, task registry, interrupt layer, device manager, and the interactive shell.

MVH Kernel is a monolithic x86\_64 bare-metal kernel that organises its internals into a set of well-defined vertical layers, each building on the one below. At the bottom sits a Hardware Abstraction Layer (HAL) that shields higher layers from direct hardware details; above it lives the memory subsystem (physical allocator, virtual memory manager, and heap); above that are the filesystem, task registry, device manager, and interrupt layer; and at the top an interactive shell exposes every kernel subsystem to you through more than 50 built-in commands. All code runs in kernel mode on a single boot processor — there is no userspace, no scheduler, and no network stack in this release.

## Layer Stack

The table below lists each layer in bottom-up order together with its primary role and key parameters.

| Layer                             | Role                         | Key details                                                                 |
| --------------------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| **HAL**                           | Hardware abstraction         | Platform init, PS/2 keyboard input, CMOS clock, PCI bus scan, system reboot |
| **Physical Page Allocator (PMM)** | Physical memory management   | 4 KiB pages; identity map limited to first 1 024 MiB                        |
| **Virtual Memory Manager (VMM)**  | Virtual address space        | 4-level paging; dynamic 4 KiB mapping/unmapping; NX, SMEP, SMAP, UMIP       |
| **Kernel Heap**                   | Dynamic kernel allocations   | 1 MiB coalescing heap; canary hardening; free poisoning                     |
| **VFS + RAMFS**                   | Filesystem abstraction       | Volatile RAM filesystem mounted as root; standard path operations           |
| **Device Manager**                | Device registry              | Up to 32 devices catalogued by type and online state                        |
| **Task Registry**                 | Kernel task tracking         | Up to 16 tasks with PID, priority, state, and creation-tick metadata        |
| **Interrupt Layer**               | IDT + PIC management         | IDT with remapped 8259 PIC; 100 Hz PIT; per-vector fire counters            |
| **Kernel Log**                    | Structured logging           | 16 KiB ring buffer; per-entry timestamp and category                        |
| **Kernel Panic**                  | Unrecoverable error handling | Full register and CR dump; decoded error flags; stack trace                 |
| **Interactive Shell**             | Operator interface           | 50+ built-in commands covering every subsystem                              |

### HAL

The HAL initialises the platform and exposes a uniform API for keyboard input (`hal_keyboard_read`), wall-clock time (`hal_clock_read`), PCI device enumeration (`hal_pci_scan`), tick counter (`hal_ticks`), uptime (`hal_uptime_seconds`), and a hard reboot (`hal_reboot`). All hardware-specific details — port I/O addresses, CMOS register layout, PIC wiring — are contained within the HAL and hidden from every layer above.

### Physical Page Allocator (PMM)

The PMM tracks physical RAM as 4 KiB pages. It initialises from the boot-supplied memory size (in KiB) and marks the kernel image as reserved. The identity map covers the first 1 024 MiB of physical address space. You allocate one or more contiguous pages with `pmm_alloc_pages` and release them with `pmm_free_pages`. The PMM exposes statistics — total, used, free, and reserved page counts together with allocation request, failure, and peak-usage counters — via `pmm_get_stats`.

### Virtual Memory Manager (VMM)

The VMM implements x86\_64 four-level paging. It dynamically maps and unmaps individual 4 KiB pages with `vmm_map_page` and `vmm_unmap_page` using a rich set of page-attribute flags. Security protections — supervisor write-protect, NX enforcement, null-page guard, and (where the CPU supports them) SMEP, SMAP, and UMIP — are applied during VMM initialisation. Kernel text pages are mapped read-only and executable; kernel data pages are mapped writable and non-executable.

### Kernel Heap

The 1 MiB coalescing heap provides `kmalloc` / `kfree` for dynamic kernel allocations. Every block carries a canary value; a corrupted canary triggers an immediate kernel panic. Freed memory is poisoned to catch use-after-free bugs at the point of the next access. Invalid double-frees and bad-pointer frees are counted and reported in heap statistics.

### VFS and RAMFS

The Virtual Filesystem provides a uniform path-based API (`vfs_chdir`, `vfs_list`, `vfs_mkdir`, `vfs_touch`, `vfs_write`, `vfs_read`, `vfs_remove`) backed by a volatile RAM filesystem mounted at the root. All filesystem state is lost when the kernel reboots.

### Device Manager

The device manager holds a registry of up to 32 kernel-managed devices. Each entry records a numeric ID, a device type (CPU, interrupt controller, timer, input, display, serial, clock, bus, or filesystem), an online flag, and a name of up to 27 characters. You register devices with `device_register` and enumerate them with `device_list`.

### Task Registry

The task registry tracks up to 16 kernel tasks. Each entry stores a PID, a priority byte, a lifecycle state (`UNUSED`, `RUNNING`, `READY`, `SLEEPING`, or `STOPPED`), a creation tick, and a name. The registry is inspectable at runtime through the shell.

### Interrupt Layer

`interrupt_init` loads the IDT and remaps the 8259 PIC so hardware IRQs start above the CPU exception vectors. The PIT is programmed to fire at 100 Hz, providing the kernel's time base. Every vector maintains a fire counter accessible via `interrupt_count`; `interrupt_total` and `interrupt_spurious_count` give system-wide totals.

### Kernel Log

The kernel log is a 16 KiB ring buffer. Each write carries a log level, an optional category string, and the message text. The ring wraps when full, discarding the oldest entries. Console mirroring can be toggled with `klog_set_console`. The full log content can be read back with `klog_copy`.

### Kernel Panic

When the kernel encounters an unrecoverable condition it calls `kernel_panic` (software panic) or `kernel_panic_exception` (hardware exception). Both paths dump all general-purpose registers (RAX–R15), the exception vector, error code, RIP, CS, and RFLAGS, then decode any recognised error flags and print a stack trace before halting.

### Interactive Shell

The shell provides more than 50 built-in commands that cover every layer described above — memory statistics, page mapping queries, device listing, task inspection, filesystem operations, PCI enumeration, CPU diagnostics, log dumping, and more. See the [Shell Overview](/shell/overview) for the full command reference.

***

## Drivers

MVH Kernel ships the following drivers, registered with the device manager at boot:

| Driver ID                         | Description                                      |
| --------------------------------- | ------------------------------------------------ |
| `vga-text-cursor`                 | VGA text-mode display with cursor control        |
| `serial-uart-16550`               | Serial UART (16550) output                       |
| `ps2-keyboard-en-us`              | PS/2 keyboard (US English layout)                |
| `x86-cpuid`                       | CPUID-based CPU feature and topology detection   |
| `x86-fpu-xsave`                   | FPU / XSAVE state management                     |
| `x86-msr-rng`                     | MSR-based hardware random number generation      |
| `intel-dts-temperature`           | Intel Digital Thermal Sensor package temperature |
| `amd-northbridge-smn-temperature` | AMD Northbridge SMN die temperature              |
| `x86-paging`                      | x86\_64 four-level page-table management         |
| `cmos-rtc`                        | CMOS real-time clock                             |
| `pci-config`                      | PCI configuration space read/write               |
| `x86-idt-pic`                     | IDT setup and 8259 PIC remapping                 |
| `x86-exception-dispatch`          | CPU exception dispatch and decode                |
| `pit-8254`                        | 8254 Programmable Interval Timer (100 Hz)        |
| `ramfs`                           | Volatile RAM filesystem backend                  |
| `vfs-root`                        | VFS root-mount layer                             |
| `device-manager`                  | Kernel device registry                           |

***

## Current Scope and Limitations

MVH Kernel 1.1.2 targets a single-processor, kernel-mode environment. The following capabilities are explicitly out of scope for this release:

* **Single boot processor only** — symmetric multiprocessing (SMP) is not supported.
* **Kernel mode only** — there is no userspace ELF loader and no privilege-level separation between user and kernel (ring 3 is unused).
* **Volatile root filesystem** — RAMFS contents do not persist across reboots.
* **Legacy PIC** — the APIC is detected but not used; the 8259 PIC remains active.
* **No ACPI boot-table handoff** — ACPI tables are not parsed.
* **Temperature monitoring** — limited to supported Intel DTS and AMD family parts.
* **No compiler stack protector** — kernel code is built without `-fstack-protector`.
* **No network, USB, or storage stack** — peripheral buses beyond PCI configuration space are not managed.