> ## 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.

# Get Started: Build and Boot MVH Kernel from Source

> Build and boot MVH Kernel from source in three steps. Requires GCC with x86_64 support, GNU Make, and GNU ld. Output is build/kernel.elf.

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.

<Steps>
  <Step title="Clone the repository">
    Clone the MVH Kernel source to your local machine and enter the project directory.

    ```bash theme={null}
    git clone https://github.com/mvhcloud/MVHKernel.git
    cd MVHKernel
    ```
  </Step>

  <Step title="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`.

    ```bash theme={null}
    make
    ```

    When the build succeeds you will find the kernel ELF binary at:

    ```
    build/kernel.elf
    ```

    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`.

    <Note>
      MVH Kernel does not include a bootloader. `build/kernel.elf` is the kernel binary only — you must load it with your own bootloader.
    </Note>
  </Step>

  <Step title="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`.

    ```asm theme={null}
    ; Example: jump to the kernel entry point after Long Mode setup
    ; rdi = available memory in KiB
    mov  rdi, <available_memory_kib>
    jmp  _kernel64_start
    ```

    <Note>
      For full boot requirements and memory layout details, see the [Boot Requirements](/concepts/boot-requirements) reference page.
    </Note>
  </Step>

  <Step title="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:

    ```
    mvh> help
    mvh> uname
    mvh> meminfo
    mvh> ls
    ```

    | Command    | What it shows                                            |
    | ---------- | -------------------------------------------------------- |
    | `help`     | Full list of available shell commands                    |
    | `uname`    | Kernel name, version, and architecture                   |
    | `meminfo`  | Physical memory map, free and used pages, PMM statistics |
    | `ls`       | Contents of the current directory in the volatile RAMFS  |
    | `features` | CPUID capabilities and enabled kernel protections        |
    | `devices`  | Registered devices and their online state                |
    | `dmesg`    | Structured kernel log ring buffer                        |
    | `lspci`    | PCI devices enumerated from the configuration space      |
  </Step>
</Steps>

## 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

* Read [Building MVH Kernel from Source](/building) for detailed compiler flags and Makefile targets.
* Read [Introduction](/introduction) for a full list of capabilities and current limitations.
* Browse the API reference starting with the [Physical Memory Manager](/api/pmm).