Skip to main content
This guide takes you from a fresh clone of the MVH Kernel repository to a running kernel with an interactive shell prompt. The entire process has four steps: clone the source, build the kernel, wire up your bootloader, and start issuing commands. You do not need any runtime library, SDK, or pre-built binary — everything is compiled from source with a standard x86_64 GCC toolchain.

​
Prerequisites

Before you begin, make sure the following tools are installed and available on your PATH:
  • GCC with x86_64 support — either a cross-compiler targeting x86_64-elf or a native gcc installation with multilib support. The build uses gcc directly; no wrapper script is required.
  • GNU Make — the build system is a plain Makefile with no additional build generator.
  • GNU ld — the linker (ld) must support the elf_x86_64 emulation (-m elf_x86_64). This is included in standard GNU Binutils.
1

Clone the repository

Clone the MVH Kernel source to your local machine and enter the project directory.
2

Build the kernel

Run make from the project root. The build system compiles every kernel module, links them with linker.ld, and writes the output binary to build/kernel.elf.
When the build succeeds you will find the kernel ELF binary at:
This is a standard ELF64 binary for x86_64 with no external runtime dependencies. To clean the build directory and remove all compiled objects, run make clean.
MVH Kernel does not include a bootloader. build/kernel.elf is the kernel binary only — you must load it with your own bootloader.
3

Integrate with your bootloader

Your bootloader must satisfy three requirements before jumping to the kernel entry point:
  1. Enter x86_64 Long Mode — the kernel entry point _kernel64_start is 64-bit code. Your bootloader must complete the transition to Long Mode before transferring control.
  2. Identity-map the first GiB — the kernel expects a 1:1 physical-to-virtual mapping covering the first 1024 MiB of address space.
  3. Pass available memory size in KiB — load the total available RAM in KiB into the first argument register (rdi / edi) before calling the entry point. This is the boot-memory-size-kib convention the PMM uses to claim its page range.
Once those conditions are met, jump to the _kernel64_start symbol exported from build/kernel.elf. The entry stub clears BSS, initialises FPU/SSE/XSAVE, and calls kernel_main.
For full boot requirements and memory layout details, see the Boot Requirements reference page.
4

First shell interaction

After a successful boot, MVH Kernel initialises all subsystems and drops into the interactive shell. You will see the mvh> prompt on the VGA text display and mirrored on the serial port (16550 UART).Try these commands to verify the kernel is working correctly:

​
What happens at boot

When _kernel64_start runs, the kernel performs the following sequence automatically:
  1. Clears the BSS segment and initialises FPU, SSE, and XSAVE.
  2. Calls kernel_main, which initialises the HAL and all hardware.
  3. Installs the IDT, remaps the 8259 PIC, and starts the PIT timer at 100 Hz.
  4. Initialises the PMM with the memory size passed by your bootloader, then sets up VMM page protections and the kernel heap.
  5. Initialises VGA, serial, PS/2 keyboard, CPUID, RTC, and PCI drivers.
  6. Mounts RAMFS as the root filesystem at /.
  7. Drops into the mvh> interactive shell.
The entire boot sequence completes in milliseconds. There is no splash screen, delay, or configuration file to parse.

​
Next steps