Building MVH Kernel from Source: Flags and Targets

Step-by-step guide to compiling MVH Kernel. Covers toolchain requirements, build flags, output artifacts, and the Makefile targets.

MVH Kernel compiles from a single, self-contained Makefile with no external build system, no package manager, and no generated configuration. You need a standard x86_64 GCC toolchain and GNU Make. This page covers every compiler flag the build uses, all Makefile targets, the output artifacts you will find after a successful build, and notes on behaviours you need to be aware of during development.

Toolchain requirements

Tool	Minimum requirement	Notes
GCC	Any version with x86_64 and freestanding support	Use x86_64-elf-gcc for a dedicated cross-compiler, or a native gcc with multilib (-m64 support). The CC variable in the Makefile defaults to gcc.
GNU ld	Any version supporting elf_x86_64 emulation	Supplied by GNU Binutils. The LD variable defaults to ld. The linker is invoked with -m elf_x86_64 -nostdlib.
GNU Make	Any modern version	No features beyond standard POSIX make are used.

If your host system’s native gcc does not support -m64 (for example, on a 32-bit host), install a x86_64-elf cross-compiler and set the CC variable when invoking make:

make CC=x86_64-elf-gcc LD=x86_64-elf-ld

Building the kernel

Run make from the repository root:

make

The build system creates the build/ directory if it does not exist, compiles each source module into a .o object file, then links everything with linker.ld into the final kernel binary.

Makefile targets

Target	Command	Description
all (default)	make	Compiles all modules and produces build/kernel.elf.
clean	make clean	Removes the entire build/ directory and all compiled artefacts.

# Build the kernel
make

# Remove all build artefacts
make clean

Compiler flags

The Makefile applies the following CFLAGS to every C source file in the kernel:

CFLAGS := -m64 -mno-red-zone -std=c11 -ffreestanding -fno-pie -fno-stack-protector \
          -fno-builtin -fno-unwind-tables -fno-asynchronous-unwind-tables \
          -fno-omit-frame-pointer -Wall -Wextra -Werror -O2 -Iinclude

The table below explains each flag and why it is required:

Flag	Purpose
-m64	Target the x86_64 (64-bit) instruction set.
-mno-red-zone	Disable the 128-byte red zone below the stack pointer. Required for kernel code because hardware interrupts do not respect the red zone and will corrupt it.
-std=c11	Compile against the C11 standard.
-ffreestanding	Declare a freestanding environment — no libc, no hosted runtime. The compiler will not assume the presence of main, printf, or any standard library function.
-fno-pie	Do not generate position-independent executable code. The kernel is linked at a fixed physical address (0x200000) and must not use GOT/PLT relocations.
-fno-stack-protector	Disable stack canary instrumentation. Stack protector requires a __stack_chk_guard symbol provided by libc, which is not available in this freestanding environment.
-fno-builtin	Prevent GCC from substituting calls to standard library builtins (e.g., replacing a loop with memset). The kernel provides its own memory routines.
-fno-unwind-tables / -fno-asynchronous-unwind-tables	Suppress .eh_frame and .eh_frame_hdr generation. Unwinding tables are unused in the kernel and add unnecessary size.
-fno-omit-frame-pointer	Required. Preserve the frame pointer (rbp) in every function. MVH Kernel’s panic handler walks the rbp chain to produce a bounded stack trace. Omitting frame pointers would break crash diagnostics.
-Wall -Wextra -Werror	Enable all standard and extra warnings and treat every warning as a build error. The kernel must compile cleanly with no suppressed warnings.
-O2	Enable level-2 optimisation. Produces faster, smaller code while remaining compatible with the other flags above.
-Iinclude	Add the include/ directory to the compiler’s header search path so all #include <mvh/...> headers resolve correctly.

Assembly source files (entry64.S and interrupt64.S) are assembled with only -m64 -c — the full CFLAGS are not applied to assembly.

Output artifacts

A successful make produces a single output file:

Artifact	Path	Description
Kernel binary	build/kernel.elf	ELF64 binary for x86_64. This is the only file you need to pass to your bootloader.

MVH Kernel does not include a bootloader. build/kernel.elf is the kernel binary only. You must load it with your own bootloader that enters x86_64 Long Mode, identity-maps the first GiB of physical memory, and jumps to _kernel64_start. See the Quickstart for integration instructions.

You can inspect the output binary with standard ELF tools:

# Verify the ELF format and architecture
file build/kernel.elf

# Inspect section layout and sizes
objdump -h build/kernel.elf

# Print the entry point address
readelf -h build/kernel.elf | grep Entry

Entry point

The kernel entry point is _kernel64_start, defined in src/entry64.S and declared as the ELF entry in linker.ld:

ENTRY(_kernel64_start)

The kernel is linked at a base address of 0x200000 (2 MiB). The linker script arranges sections in the following order:

Section	Alignment	Permissions
.text	4 KiB	Read, Execute
.rodata	4 KiB	Read only
.data	4 KiB	Read, Write
.bss	4 KiB	Read, Write (zero-initialised by entry stub)

The .text.entry section — containing _kernel64_start — is kept first within .text via a KEEP directive so the entry point always lands at the lowest address in the binary.

Kernel modules compiled

The Makefile compiles the following modules into the final binary:

Architecture & Entry

entry64.S       — 64-bit entry point and halt loop
interrupt64.S   — Low-level interrupt stubs
arch/interrupt.c — IDT, PIC remapping, interrupt dispatch

Notes on faulttest

The faulttest and faulttest page shell commands intentionally halt the kernel. faulttest triggers an exception without a CPU error code to validate the exception-dispatch path. faulttest page triggers a page fault to validate CR2 reporting and page-fault error-code decoding. Do not run either command in a production or integration environment unless you intend to test panic handling and are prepared for the system to stop.