> ## 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: x86_64 Bare-Metal Kernel — Introduction
> MVH Kernel is an independent ELF64 kernel for x86_64. Learn what it provides, its capabilities, known limitations, and how documentation is maintained.
MVH Kernel is an independent, open-source ELF64 bare-metal kernel for the x86\_64 architecture, developed and maintained by MVH Cloud. It is written in C and targets developers who are building their own operating system or embedded platform on top of a custom bootloader. The kernel enters directly in x86\_64 Long Mode, takes over hardware initialisation, and provides a stable set of subsystems — memory management, interrupt handling, a virtual filesystem, device management, and a hardware abstraction layer — that you can build on immediately.
This documentation is **not regularly updated**. The pages here reflect the kernel at a point in time and may lag behind recent releases. For the most accurate and up-to-date information, refer to the [source code](https://github.com/mvhcloud/MVHKernel) and the [CHANGELOG](https://github.com/mvhcloud/MVHKernel/blob/main/CHANGELOG.md) directly.
## What is MVH Kernel?
MVH Kernel is a standalone kernel — it does not include a bootloader, operating system, libc, or userspace runtime. Its job is to initialise the x86\_64 hardware environment, manage physical and virtual memory, expose a virtual filesystem, dispatch hardware and software interrupts, enumerate PCI devices, and present an interactive shell for live introspection. You supply a bootloader that enters Long Mode, identity-maps the first GiB, and jumps to `_kernel64_start`; MVH Kernel handles everything from that point forward.
The kernel is licensed under the MIT License. Source code, the manifest, and the release log are all available in the project repository.
## Key capabilities
MVH Kernel 1.1.2 ships with the following features and subsystems:
* **Hardware Abstraction Layer (HAL)** — unified platform initialisation, input routing, timer, RTC, PCI, and reboot abstractions.
* **Physical Memory Manager (PMM)** — 4 KiB page allocator limited to the memory range reported by the bootloader, with allocation statistics and peak-use tracking.
* **Virtual Memory Manager (VMM)** — dynamic 4 KiB page mapping and unmapping with read-only executable kernel text, non-executable data sections, NX enforcement, supervisor write protection, a null-page guard, and SMEP/SMAP/UMIP protections where available.
* **Kernel Heap** — one-MiB coalescing heap with `kmalloc` and `kfree`, heap canaries, corruption panic, free poisoning, invalid-free tracking, and fragmentation statistics.
* **Virtual Filesystem (VFS)** — clean VFS boundary with RAMFS mounted as the root filesystem, supporting directories and text files.
* **Interrupt Layer** — x86\_64 IDT, remapped 8259 PIC, Intel 8254-compatible PIT system timer at 100 Hz, CPU exception gates for vectors 0–31, and per-vector interrupt counters.
* **Device Manager** — registry-based device manager with typed online state.
* **PCI Enumeration** — configuration-space PCI driver with the `lspci` shell command.
* **CPU Diagnostics** — CPUID vendor, model, family, APIC, cache, SIMD, TSC, and RNG capability detection; FPU, SSE, and XSAVE initialisation with AVX support where available.
* **CPU Temperature** — Intel Digital Thermal Sensor (DTS) MSRs, AMD Family 10h–16h northbridge Tctl, and AMD Family 17h–1Ah SMN Tctl, all with range validation.
* **Hardware RNG** — capability-guarded MSR access to the processor's hardware random number generator.
* **Kernel Panic** — stable panic codes, decoded page-fault and selector-error flags, control-register and general-register dumps, and frame-pointer stack traces on both VGA and serial output.
* **Kernel Log** — 16 KiB structured timestamped ring buffer, readable with `dmesg`.
* **Interactive Shell** — `mvh>` prompt with over 40 built-in commands covering filesystem navigation, memory inspection, device listing, CPU information, diagnostics, and more.
* **Synchronisation** — atomic 32-bit operations, spinlocks, and mutex primitives.
* **Task Registry** — kernel task registry with PID, priority, and execution-state metadata.
* **Language Support** — runtime language switching between English, German, Spanish, and French (English US default).
* **Drivers** — VGA text cursor, 16550 UART serial, PS/2 keyboard (English US layout), CMOS RTC, and x86 paging.
## Current limitations
The following limitations apply to MVH Kernel 1.1.2. Read this section carefully before committing to an integration that requires any of these capabilities.
| Limitation | Detail |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Single boot processor, kernel mode only** | The kernel runs on the boot processor in Ring 0. Multi-core startup (APIC, SIPI) and Ring 3 userspace are not implemented. |
| **Volatile root filesystem** | RAMFS is reset on every boot. No persistent disk filesystem (ext2, FAT, NVMe, etc.) is present. |
| **No userspace ELF loader** | You cannot load or execute ELF binaries from within the kernel at runtime. |
| **Legacy PIC active — APIC detection only** | The 8259 PIC is remapped and active. APIC, Local APIC, and IOAPIC are detected but not activated; HPET is disabled until verified firmware-table handoff is available. |
| **No ACPI boot table handoff** | ACPI, HPET, and related firmware table parsing are not implemented. |
| **CPU temperature limited to supported families** | Temperature readings are available only for Intel DTS-capable CPUs and AMD Families 10h–16h (northbridge Tctl) and 17h–1Ah (SMN Tctl). QEMU typically exposes no usable thermal sensor and the shell reports the value as unavailable. |
| **No compiler stack protector** | `-fno-stack-protector` is set. Stack canary instrumentation requires libc support that is not available in this freestanding environment. |
| **No network, USB, or persistent storage stack** | Networking, USB, NVMe, and any form of persistent storage remain future milestones. |
## Architecture overview
MVH Kernel is organised into the following layers, executed in order at boot:
1. **Entry (`_kernel64_start`)** — clears the BSS segment, initialises FPU/SSE/XSAVE, and transfers control to `kernel_main`.
2. **HAL** — configures the platform and coordinates all subsequent hardware initialisation.
3. **Interrupt layer** — installs the IDT, remaps the PIC, and sets up the PIT timer at 100 Hz.
4. **Memory** — the PMM claims the reported memory range; the VMM applies kernel page protections; the heap initialises its one-MiB arena.
5. **Drivers** — VGA, serial, PS/2 keyboard, CPUID, RTC, and PCI drivers register with the device manager.
6. **VFS / RAMFS** — the VFS boundary is established and RAMFS is mounted as `/`.
7. **Shell** — the kernel drops into the interactive `mvh>` shell, which runs in an infinite read-execute loop.
The kernel is linked at physical address `0x200000` (2 MiB) by the linker script. The `.text` section is read-only and executable; `.rodata`, `.data`, and `.bss` are non-executable. The first 4 KiB (null page) is explicitly unmapped.
## Version and compatibility
| Property | Value |
| ---------------------------- | ---------- |
| **Version** | 1.1.2 |
| **ABI** | 1 |
| **Release series** | 1.1 |
| **Backward compatible with** | 1.1, 1.1.1 |
| **Architecture** | x86\_64 |
| **Output format** | ELF64 |
| **License** | MIT |
Version 1.1.2 is backward compatible with 1.1 and 1.1.1 within the same ABI version. If you are integrating against the ABI-1 interface, no changes to your bootloader integration are required when upgrading within the 1.1 release series.