A minimal VMM in Rust with Apple Hypervisor

2026-04-22T00:00:00+00:00

Virtual Machine Monitor</h1>

Previously</a>, we implemented a VMM with KVM for an x86_64 processor. This time we'll do the same thing — implement a VMM from scratch — but on Apple Silicon macOS using the Hypervisor framework.</p>

On the surface, KVM and Apple Hypervisor APIs look very similar:</p>

Create a VM</li>

Set up memory for it (similar to libc's

mmap</code> and munmap</code>)</li>

Create a vCPU and set up its registers</li>

In a loop, run the vCPU and handle any exit events</li>

Clean up by closing file descriptors (KVM) or calling destroy methods (Apple Hypervisor)</li>
</ul>

Just see this image from the official Hypervisor docs</a>:</p>
</p>
Like before, we'll use minimal external dependencies, but this time we'll go a bit deeper — generate Rust bindings for Hypervisor APIs, use ARM assembly for guest code instead of raw binary, and read the output generated by the guest via a general-purpose register.</p>
Rust Bindings for Hypervisor API</h2>
bindgen</code></a> automatically generates Rust FFI bindings for C/C++ libraries.</p>
It takes a wrapper header file as input. This wrapper file includes the header files of interest — in our case, the Hypervisor framework header:</p>
wrapper.h</code>:</p>
#</span>include</span> "</span>Hypervisor/Hypervisor.h</span>"</span></span></code></pre>
How do we locate the header file for Hypervisor on macOS? By using the xcrun</code> CLI:</p>
$</span> xcrun</span> -</span>sdk</span> macosx</span> -</span>-show-sdk-path</span></span>
/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk</span></span>
</span>
#</span> It links to installed SDK version:</span></span>
$</span> readlink</span> /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk</span></span>
MacOSX26.4.sdk</span></span></code></pre>
Frameworks reside in /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks</code>. For Hypervisor headers:</p>
$</span> ls</span> /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/Hypervisor.framework/Headers/</span></span>
hv_arch_vmx.h</span>       hv_gic_parameters.h</span> hv_sme_config.h</span>     hv_vm_allocate.h</span>    hv.h</span></span>
hv_arch_x86.h</span>       hv_gic_state.h</span>      hv_types.h</span>          hv_vm_config.h</span>      Hypervisor.h</span></span>
hv_base.h</span>           hv_gic_types.h</span>      hv_vcpu_config.h</span>    hv_vm_types.h</span></span>
hv_error.h</span>          hv_gic.h</span>            hv_vcpu_types.h</span>     hv_vm.h</span></span>
hv_gic_config.h</span>     hv_intr.h</span>           hv_vcpu.h</span>           hv_vmx.h</span></span></code></pre>
Hypervisor.h</code> already includes all the other header files for both x86_64 and arm64, so in our wrapper.h</code> we just need to include this single file.</p>
build.rs</h3>
First, we add a build-time dependency in Cargo.toml</code> via cargo add --build bindgen</code>.</p>
Now we have everything to write the build script that generates Rust bindings from wrapper.h</code> into bindings.rs</code>:</p>
use</span> std</span>::</span>{</span>path</span>::</span>PathBuf</span>,</span> process</span>::</span>Command</span>}</span>;</span></span>
</span>
fn</span> get_sdk_path</span>(</span>)</span> -></span> String</span> {</span></span>
    let</span> output</span> =</span> Command</span>::</span>new</span>(</span>"</span>xcrun</span>"</span>)</span></span>
        .</span>arg</span>(</span>"</span>-sdk</span>"</span>)</span></span>
        .</span>arg</span>(</span>"</span>macosx</span>"</span>)</span></span>
        .</span>arg</span>(</span>"</span>--show-sdk-path</span>"</span>)</span></span>
        .</span>output</span>(</span>)</span></span>
        .</span>expect</span>(</span>"</span>failed to run xcrun -sdk macosx --show-sdk-path</span>"</span>)</span>;</span></span>
</span>
    if</span> !</span>output</span>.</span>status</span>.</span>success</span>(</span>)</span> {</span></span>
        panic!</span>(</span></span>
            "</span>failed to get sdk path: </span>{</span>}</span>"</span>,</span></span>
            String</span>::</span>from_utf8_lossy</span>(</span>output</span>.</span>stderr</span>.</span>as_ref</span>(</span>)</span>)</span></span>
        )</span>;</span></span>
    }</span></span>
</span>
    let</span> sdk_path</span>:</span> String</span> =</span> String</span>::</span>from_utf8_lossy</span>(</span>output</span>.</span>stdout</span>.</span>as_ref</span>(</span>)</span>)</span>.</span>into</span>(</span>)</span>;</span></span>
</span>
    sdk_path</span>.</span>trim</span>(</span>)</span>.</span>into</span>(</span>)</span></span>
}</span></span>
</span>
fn</span> main</span>(</span>)</span> {</span></span>
    let</span> binding_rs_path</span> =</span></span>
        PathBuf</span>::</span>from</span>(</span>std</span>::</span>env</span>::</span>var</span>(</span>"</span>OUT_DIR</span>"</span>)</span>.</span>expect</span>(</span>"</span>OUT_DIR env var not present</span>"</span>)</span>)</span></span>
            .</span>join</span>(</span>"</span>bindings.rs</span>"</span>)</span>;</span></span>
</span>
    let</span> sdk_path</span> =</span> get_sdk_path</span>(</span>)</span>;</span></span>
</span>
    bindgen</span>::</span>builder</span>(</span>)</span></span>
        .</span>header</span>(</span>"</span>wrapper.h</span>"</span>)</span></span>
        .</span>clang_arg</span>(</span>format!</span>(</span>"</span>-F</span>{</span>}</span>/System/Library/Frameworks</span>"</span>,</span> sdk_path</span>)</span>)</span></span>
        .</span>derive_debug</span>(</span>true</span>)</span></span>
        .</span>derive_default</span>(</span>true</span>)</span></span>
        .</span>generate</span>(</span>)</span></span>
        .</span>expect</span>(</span>"</span>failed to generate bindings</span>"</span>)</span></span>
        .</span>write_to_file</span>(</span>binding_rs_path</span>)</span></span>
        .</span>expect</span>(</span>"</span>failed to write bindings.rs</span>"</span>)</span>;</span></span>
</span>
    println!</span>(</span>"</span>cargo:rustc-link-lib=framework=Hypervisor</span>"</span>)</span>;</span></span>
    (</span>)</span></span>
}</span></span></code></pre>
bindgen</code> uses clang to process header files, so we need to provide the framework search path via the -F</code> flag. Without it, we'd see errors like "Hypervisor/Hypervisor.h" file not found</code> — that's why we resolve the SDK path first.</p>
From man clang</code> on macOS:</p>

-F<directory></p>
Add the specified directory to the search path for framework include files.</p>
</blockquote>
We also need to tell rustc</code> which system library to link against via rustc-link-lib</a>. Without this, cargo build</code> will fail with "undefined symbols" when we use functions from the generated bindings.</p>
We can now use the generated bindings.rs</code> as follows:</p>
main.rs</code>:</p>
mod</span> bindings</span> {</span></span>
    include!</span>(</span>concat!</span>(</span>env!</span>(</span>"</span>OUT_DIR</span>"</span>)</span>,</span> "</span>/bindings.rs</span>"</span>)</span>)</span>;</span></span>
}</span></span>
</span>
fn</span> main</span>(</span>)</span> {</span>}</span></span></code></pre>
The env!</code> macro retrieves an environment variable at compile time, as opposed to std::env::var</code> which reads it at runtime.</p>
The included file is textually inserted into the surrounding code, so we access its symbols like bindings::hv_vm_create</code>.</p>
Create a VM</h2>
#</span>!</span>[</span>allow</span>(</span>non_upper_case_globals</span>)</span>]</span></span>
#</span>!</span>[</span>allow</span>(</span>non_camel_case_types</span>)</span>]</span></span>
#</span>!</span>[</span>allow</span>(</span>non_snake_case</span>)</span>]</span></span>
#</span>!</span>[</span>allow</span>(</span>unnecessary_transmutes</span>)</span>]</span></span>
#</span>!</span>[</span>allow</span>(</span>improper_ctypes</span>)</span>]</span></span>
#</span>!</span>[</span>allow</span>(</span>unused</span>)</span>]</span></span>
</span>
use</span> std</span>::</span>error</span>::</span>Error</span>;</span></span>
</span>
use</span> crate</span>::</span>bindings</span>::</span>{</span></span>
    HV_BAD_ARGUMENT</span>,</span> HV_BUSY</span>,</span> HV_ERROR</span>,</span> HV_NO_DEVICE</span>,</span> HV_NO_RESOURCES</span>,</span> HV_SUCCESS</span>,</span> HV_UNSUPPORTED</span>,</span></span>
    hv_vm_create</span>,</span></span>
}</span>;</span></span>
</span>
mod</span> bindings</span> {</span></span>
    include!</span>(</span>concat!</span>(</span>env!</span>(</span>"</span>OUT_DIR</span>"</span>)</span>,</span> "</span>/bindings.rs</span>"</span>)</span>)</span>;</span></span>
}</span></span>
</span>
fn</span> main</span>(</span>)</span> -></span> Result</span><</span>(</span>)</span>,</span> Box</span><</span>dyn</span> Error</span>></span>></span> {</span></span>
</span>
    ///</span> 1. Create a VM</span></span>
</span>
    let</span> val</span> =</span> unsafe</span> {</span> hv_vm_create</span>(</span>std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>)</span> }</span>;</span></span>
</span>
    match</span> val</span> {</span></span>
        HV_SUCCESS</span> =></span> println!</span>(</span>"</span>HV_SUCCESS: The operation completed successfully.</span>"</span>)</span>,</span></span>
        HV_ERROR</span> =></span> eprintln!</span>(</span>"</span>HV_ERROR: The operation was unsuccessful.</span>"</span>)</span>,</span></span>
        HV_BUSY</span> =></span> eprintln!</span>(</span></span>
            "</span>HV_BUSY: The operation was unsuccessful because the owning resource was busy.</span>"</span></span>
        )</span>,</span></span>
        HV_BAD_ARGUMENT</span> =></span> eprintln!</span>(</span></span>
            "</span>HV_BAD_ARGUMENT: The operation was unsuccessful because the function call had an invalid argument.</span>"</span></span>
        )</span>,</span></span>
        HV_NO_RESOURCES</span> =></span> eprintln!</span>(</span></span>
            "</span>HV_NO_RESOURCES: The operation was unsuccessful because the host had no resources available to complete the request.</span>"</span></span>
        )</span>,</span></span>
        HV_NO_DEVICE</span> =></span> eprintln!</span>(</span></span>
            "</span>HV_NO_DEVICE: The operation was unsuccessful because no VM or vCPU was available.</span>"</span></span>
        )</span>,</span></span>
        HV_UNSUPPORTED</span> =></span> {</span></span>
            eprintln!</span>(</span>"</span>HV_UNSUPPORTED: The operation requested isn’t supported by the hypervisor.</span>"</span>)</span></span>
        }</span></span>
        _</span> =></span> eprintln!</span>(</span>"</span>unknown </span>{</span>val</span>}</span>"</span>)</span>,</span></span>
    }</span></span>
</span>
    Ok</span>(</span>(</span>)</span>)</span></span>
}</span></span></code></pre>
The generated symbol names come from C header files and don't follow Rust naming conventions, so we add #![allow(...)]</code> attributes at the top to suppress warnings.</p>
The match statement for the return value is straight from the documentation for hv_return_t</code></a>.</p>
Running this with cargo run</code>, we see:</p>

unknown -85377017</p>
</blockquote>
This is because our VMM must have the com.apple.security.hypervisor</code> entitlement. Let's create an entitlement file:</p>
virt.entitlements</code>:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0</span>"</span> encoding</span>=</span>"</span>UTF-8</span>"</span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0</span>"</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span>com.apple.security.hypervisor</span></</span>key</span>></span></span>
        <</span>true</span>/></span></span>
    </</span>dict</span>></span></span>
</</span>plist</span>></span></span></code></pre>
For local development, self-sign the debug binary:</p>
codesign</span> -</span>-sign</span> -</span> -</span>-force</span> -</span>-entitlements=virt.entitlements</span> ../target/debug/minimal-apple-hypervisor</span></span></code></pre>
Now, if we rerun our VMM:</p>

$ ../target/debug/minimal-apple-hypervisor</p>
HV_SUCCESS: The operation completed successfully.</p>
</blockquote>
All Hypervisor APIs return hv_return_t</code>, so to keep things DRY, let's create an hv_call!</code> macro and an HVError</code> struct.</p>
#</span>[</span>derive</span>(</span>Debug</span>)</span>]</span></span>
pub</span> struct</span> HVError</span>(</span>i32</span>)</span>;</span></span>
impl</span> std</span>::</span>error</span>::</span>Error</span> for</span> HVError</span> {</span>}</span></span>
</span>
impl</span> Display</span> for</span> HVError</span> {</span></span>
    fn</span> fmt</span>(</span>&</span>self</span>,</span> f</span>:</span> &</span>mut</span> std</span>::</span>fmt</span>::</span>Formatter</span><</span>'</span>_</span>></span>)</span> -></span> std</span>::</span>fmt</span>::</span>Result</span> {</span></span>
        write!</span>(</span>f</span>,</span> "</span>{</span>}</span>"</span>,</span> self</span>.</span>0</span>)</span></span>
    }</span></span>
}</span></span>
</span>
impl</span> HVError</span> {</span></span>
    pub</span> fn</span> from_error</span>(</span>err</span>:</span> i32</span>)</span> -></span> Self</span> {</span></span>
        HVError</span>(</span>err</span>)</span></span>
    }</span></span>
}</span></span>
</span>
macro_rules!</span> hv_call</span> {</span></span>
    (</span>$</span>e</span>:</span>expr</span>)</span> =></span> {</span>{</span></span>
        let</span> val</span> =</span> unsafe</span> {</span> $</span>e</span> }</span>;</span></span>
</span>
        match</span> val</span> {</span></span>
            HV_SUCCESS</span> =></span> println!</span>(</span>"</span>HV_SUCCESS: The operation completed successfully.</span>"</span>)</span>,</span></span>
            HV_ERROR</span> =></span> eprintln!</span>(</span>"</span>HV_ERROR: The operation was unsuccessful.</span>"</span>)</span>,</span></span>
            HV_BUSY</span> =></span> eprintln!</span>(</span></span>
                "</span>HV_BUSY: The operation was unsuccessful because the owning resource was busy.</span>"</span></span>
            )</span>,</span></span>
            HV_BAD_ARGUMENT</span> =></span> eprintln!</span>(</span></span>
                "</span>HV_BAD_ARGUMENT: The operation was unsuccessful because the function call had an invalid argument.</span>"</span></span>
            )</span>,</span></span>
            HV_NO_RESOURCES</span> =></span> eprintln!</span>(</span></span>
                "</span>HV_NO_RESOURCES: The operation was unsuccessful because the host had no resources available to complete the request.</span>"</span></span>
            )</span>,</span></span>
            HV_NO_DEVICE</span> =></span> eprintln!</span>(</span></span>
                "</span>HV_NO_DEVICE: The operation was unsuccessful because no VM or vCPU was available.</span>"</span></span>
            )</span>,</span></span>
            HV_UNSUPPORTED</span> =></span> {</span></span>
                eprintln!</span>(</span>"</span>HV_UNSUPPORTED: The operation requested isn’t supported by the hypervisor.</span>"</span>)</span></span>
            }</span></span>
            _</span> =></span> eprintln!</span>(</span>"</span>unknown </span>{</span>val</span>}</span>"</span>)</span>,</span></span>
        }</span></span>
</span>
        match</span> val</span> {</span></span>
            HV_SUCCESS</span> =></span> Ok</span>(</span>val</span>)</span>,</span></span>
            _</span> =></span> Err</span>(</span>HVError</span>::</span>from_error</span>(</span>val</span>)</span>)</span></span>
        }</span></span>
    }</span>}</span>;</span></span>
}</span></span></code></pre>
With this, our VM creation is simply:</p>
///</span> 1. Create a VM</span></span>
let</span> vm</span> =</span> hv_call!</span>(</span>hv_vm_create</span>(</span>std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>)</span>)</span>?</span>;</span></span></code></pre>Create VM Memory</h2>
For this, we need libc</code> for mmap</code> and munmap</code> system calls, so we add our only runtime dependency: cargo add libc</code>.
We ask the system for read-write memory, but when mapping it to the hypervisor with hv_vm_map</code>, we make it read-write-execute.</p>
///</span> 2 blocks/pages of 16KiB - on Apple Silicon default page size is 16KiB</span></span>
const</span> VM_MEMORY_SIZE</span>:</span> usize</span> =</span> 2</span> *</span> 16384</span>;</span></span>
</span>
struct</span> Mmap</span> {</span></span>
    pub</span> addr</span>:</span> *</span>mut</span> std</span>::</span>os</span>::</span>raw</span>::</span>c_void</span>,</span></span>
    pub</span> len</span>:</span> usize</span>,</span></span>
}</span></span>
</span>
impl</span> Mmap</span> {</span></span>
    pub</span> fn</span> new</span>(</span>len</span>:</span> usize</span>)</span> -></span> Result</span><</span>Self</span>,</span> Box</span><</span>dyn</span> Error</span>></span>></span> {</span></span>
        let</span> addr</span> =</span> unsafe</span> {</span></span>
            libc</span>::</span>mmap</span>(</span></span>
                std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>,</span></span>
                len</span>,</span></span>
                libc</span>::</span>PROT_READ</span> |</span> libc</span>::</span>PROT_WRITE</span>,</span></span>
                libc</span>::</span>MAP_ANON</span> |</span> libc</span>::</span>MAP_PRIVATE</span>,</span></span>
                -</span>1</span>,</span></span>
                0</span>,</span></span>
            )</span></span>
        }</span>;</span></span>
</span>
        if</span> addr</span> ==</span> libc</span>::</span>MAP_FAILED</span> {</span></span>
            return</span> Err</span>(</span>format!</span>(</span>"</span>failed to mmap: </span>{</span>}</span>"</span>,</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>)</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
</span>
        Ok</span>(</span>Mmap</span> {</span> addr</span>,</span> len</span> }</span>)</span></span>
    }</span></span>
}</span></span>
</span>
impl</span> Drop</span> for</span> Mmap</span> {</span></span>
    fn</span> drop</span>(</span>&</span>mut</span> self</span>)</span> {</span></span>
        if</span> !</span>self</span>.</span>addr</span>.</span>is_null</span>(</span>)</span> {</span></span>
            unsafe</span> {</span></span>
                libc</span>::</span>munmap</span>(</span>self</span>.</span>addr</span>,</span> self</span>.</span>len</span>)</span>;</span></span>
            }</span></span>
        }</span></span>
    }</span></span>
}</span></span>
</span>
//</span> in main:</span></span>
</span>
///</span> 2. Create and set up VM memory.</span></span>
///</span> Map a region in VMM's virtual address space to guest physical address space</span></span>
let</span> vm_mmap</span> =</span> Mmap</span>::</span>new</span>(</span>VM_MEMORY_SIZE</span>)</span>?</span>;</span></span>
</span>
let</span> vm_map</span> =</span> hv_call!</span>(</span>hv_vm_map</span>(</span></span>
    vm_mmap</span>.</span>addr</span>,</span></span>
    0</span>,</span></span>
    VM_MEMORY_SIZE</span>,</span></span>
    (</span>HV_MEMORY_READ</span> |</span> HV_MEMORY_WRITE</span> |</span> HV_MEMORY_EXEC</span>)</span>.</span>into</span>(</span>)</span>,</span></span>
)</span>)</span>?</span>;</span></span></code></pre>Copy Guest Code</h2>
We want to run the whole VM lifecycle, so we implement simple guest code that does two things:</p>

Store a value in a CPU register (x0</code>)</li>
Execute an instruction (hvc</code>) that causes the VM to exit and returns control to our VMM</li>
</ol>
It's simple enough that we can write it in assembly and let Rust take care of assembling it into machine code.</p>
///</span> Guest Code</span></span>
global_asm!</span>(</span></span>
    r</span>#</span>"</span></span>
    .global _guest_code_start</span></span>
    .global _guest_code_end</span></span>
    .align 4</span></span>
_guest_code_start:</span></span>
    mov x0, #0x41   // Move a value in general purpose register, so we can see it after vcpu exit.</span></span>
    hvc #0          // Hypervisor call - will cause exit</span></span>
_guest_code_end:</span></span>
    "</span>#</span></span>
)</span>;</span></span>
</span>
unsafe</span> extern</span> "</span>C</span>"</span> {</span></span>
    static</span> guest_code_start</span>:</span> u8</span>;</span></span>
    static</span> guest_code_end</span>:</span> u8</span>;</span></span>
}</span></span>
</span>
fn</span> guest_code</span>(</span>)</span> -></span> &</span>'</span>static</span> [</span>u8</span>]</span> {</span></span>
    unsafe</span> {</span></span>
        let</span> start</span> =</span> &</span>guest_code_start</span> as</span> *</span>const</span> u8</span>;</span></span>
        let</span> end</span> =</span> &</span>guest_code_end</span> as</span> *</span>const</span> u8</span>;</span></span>
        let</span> len</span> =</span> end</span>.</span>offset_from</span>(</span>start</span>)</span> as</span> usize</span>;</span></span>
        std</span>::</span>slice</span>::</span>from_raw_parts</span>(</span>start</span>,</span> len</span>)</span></span>
    }</span></span>
}</span></span></code></pre>
We place code between two labels exported as global symbols, expose those labels to Rust via extern</code> declarations, and then read the bytes between them as raw data to copy into guest memory:</p>
///</span> 3. Copy Guest Code</span></span>
unsafe</span> {</span></span>
    let</span> code</span> =</span> guest_code</span>(</span>)</span>;</span></span>
    std</span>::</span>ptr</span>::</span>copy_nonoverlapping</span>(</span>code</span>.</span>as_ptr</span>(</span>)</span>,</span> vm_mmap</span>.</span>addr </span>as</span> *</span>mut</span> u8</span>,</span> code</span>.</span>len</span>(</span>)</span>)</span>;</span></span>
}</span></span></code></pre>
Let's dissect the guest code machinery. We use global_asm!</code> because this assembly isn't scoped to a function — it emits instructions directly into the VMM binary. Inside the macro, we mark the start and end boundaries of our guest code with labels and export them as .global</code> symbols. They need to be .global</code> so the linker knows where they're defined — we then reference them via extern "C"</code> and let the linker resolve them for us.</p>
From the assembly perspective, labels represent addresses — they mark specific positions in the compiled binary. By placing them at the start and end of our guest code, we can determine exactly where it lives in memory.</p>
From Rust's perspective, guest_code_start</code> and guest_code_end</code> are two static variables of type u8</code> that exist somewhere in memory. Their byte values happen to be the first bytes of the corresponding instructions in binary form.</p>
For our purposes, the declared type is irrelevant — we only need their addresses (&guest_code_start as *const u8</code> and &guest_code_end as *const u8</code>) to perform pointer arithmetic and obtain a &'static [u8]</code> slice of the guest code.</p>
The leading underscore on _guest_code_start</code> and _guest_code_end</code> in assembly is a macOS convention — the Mach-O object format prefixes C symbols with an underscore.</p>
Create a vCPU</h2>
///</span> 4. Create a virtual CPU</span></span>
let</span> mut</span> vcpu_exit</span> =</span> std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>;</span></span>
let</span> mut</span> id</span> =</span> 0</span>;</span></span>
let</span> vcpu</span> =</span> hv_call!</span>(</span>hv_vcpu_create</span>(</span></span>
    &</span>mut</span> id</span>,</span></span>
    &</span>mut</span> vcpu_exit</span>,</span></span>
    std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span></span>
)</span>)</span>?</span>;</span></span></code></pre>
On successful creation of a vCPU, hv_vcpu_create</code> stores the CPU id in id</code> and a pointer to exit information in vcpu_exit</code>.
Later, when we run the vCPU and handle exit events, the exit details will be available through vcpu_exit</code>.</p>
Set Up CPU Registers</h2>
Here we set the program counter (PC) to 0</code> — the guest physical address where we copied our code — and configure the processor state register (CPSR) to disable interrupts.</p>
///</span> 5. Setup CPU registers</span></span>
let</span> set_reg</span> =</span> hv_call!</span>(</span>hv_vcpu_set_reg</span>(</span>id</span>,</span> hv_reg_t_HV_REG_PC</span>,</span> 0</span>)</span>)</span>?</span>;</span></span>
</span>
//</span> Set Program State Register to basically disable all interrupts.</span></span>
//</span> Put the CPU in EL1h (EL1 using SP_EL1) with interrupts masked. Value 0x3c5:</span></span>
//</span> bits [3:0] = 0101 → EL1h mode</span></span>
//</span> bit 6 (F) = 1 → mask FIQ</span></span>
//</span> bit 7 (I) = 1 → mask IRQ</span></span>
//</span> bit 8 (A) = 1 → mask SError</span></span>
//</span> bit 9 (D) = 1 → mask debug</span></span>
hv_call!</span>(</span>hv_vcpu_set_reg</span>(</span>id</span>,</span> hv_reg_t_HV_REG_CPSR</span>,</span> 0x3c5</span>)</span>)</span>?</span>;</span></span></code></pre>Run the vCPU</h2>
Now all that's left is to run the vCPU and handle exit events by inspecting vcpu_exit</code>.</p>
Since we expect hvc</code> to cause the exit, we verify this by checking the exception class in the syndrome register. If it matches, we read the x0</code> register to confirm our guest code stored the expected value.</p>
///</span> 6. Run the vCPU</span></span>
loop</span> {</span></span>
    hv_call!</span>(</span>hv_vcpu_run</span>(</span>id</span>)</span>)</span>?</span>;</span></span>
    let</span> exit</span> =</span> unsafe</span> {</span> &</span>*</span>vcpu_exit</span> }</span>;</span></span>
</span>
    ///</span> 7. Handle vCPU exit event</span></span>
    println!</span>(</span>"</span>exit reason: </span>{</span>}</span>"</span>,</span> exit</span>.</span>reason</span>)</span>;</span></span>
    println!</span>(</span>"</span>  physical_address: </span>{</span>:#x</span>}</span>"</span>,</span> exit</span>.</span>exception</span>.</span>physical_address</span>)</span>;</span></span>
    println!</span>(</span>"</span>  virtual_address: </span>{</span>:#x</span>}</span>"</span>,</span> exit</span>.</span>exception</span>.</span>virtual_address</span>)</span>;</span></span>
    println!</span>(</span>"</span>  syndrome: </span>{</span>:#x</span>}</span>"</span>,</span> exit</span>.</span>exception</span>.</span>syndrome</span>)</span>;</span></span>
</span>
    //</span> check that HVC got us here</span></span>
    //</span> https://developer.arm.com/documentation/ddi0602/2022-09/Base-Instructions/HVC--Hypervisor-Call-</span></span>
    //</span> https://developer.arm.com/documentation/111107/2026-03/AArch64-Registers/ESR-EL1--Exception-Syndrome-Register--EL1-</span></span>
    //</span> exception class bits [31:26]</span></span>
    let</span> exception_class</span> =</span> (</span>exit</span>.</span>exception</span>.</span>syndrome </span>>></span> 26</span>)</span> &</span> 0x3f</span>;</span></span>
    if</span> exception_class</span> ==</span> 0x16</span> {</span></span>
        println!</span>(</span>"</span>HVC executed in Guest</span>"</span>)</span>;</span></span>
        //</span> get the value of x0</span></span>
        let</span> mut</span> x0</span> =</span> 0</span>u64</span>;</span></span>
        hv_call!</span>(</span>hv_vcpu_get_reg</span>(</span>id</span>,</span> hv_reg_t_HV_REG_X0</span>,</span> &</span>mut</span> x0</span>)</span>)</span>?</span>;</span></span>
        println!</span>(</span>"</span>X0 from Guest: </span>{</span>x0:#x</span>}</span>"</span>)</span>;</span></span>
    }</span></span>
</span>
    break</span>;</span></span>
}</span></span></code></pre>Cleanup</h2>
Let's clean up in reverse order of creation — destroy the vCPU, unmap the memory region, and finally destroy the VM:</p>
///</span> 8. Cleanup: destroy vcpu, unmap memory region, destroy vm</span></span>
let</span> vcpu_destroy</span> =</span> hv_call!</span>(</span>hv_vcpu_destroy</span>(</span>id</span>)</span>)</span>?</span>;</span></span>
let</span> vm_unmap</span> =</span> hv_call!</span>(</span>hv_vm_unmap</span>(</span>0</span>,</span> VM_MEMORY_SIZE</span>)</span>)</span>?</span>;</span></span>
let</span> vm_destroy</span> =</span> hv_call!</span>(</span>hv_vm_destroy</span>(</span>)</span>)</span>?</span>;</span></span></code></pre>
That's all it takes to run the VM lifecycle</a> from the official docs!</p>
Closing Thoughts</h1>
The steps to run a VM lifecycle with KVM and Apple Hypervisor are conceptually similar. While our VM doesn't do anything useful, it's a good exercise to explore various aspects of systems programming.</p>
Try modifying the value of x0</code> in the guest code and explore the full source code</a>!</p>
Let me know your feedback in the comment section below!</p>

A minimal VMM in Rust with KVM

2026-04-15T00:00:00+00:00

Virtual Machine Monitor</h1>
If you've ever wondered how tools like Cloud Hypervisor or Firecracker work under the hood, building a minimal VMM is one of the best ways to learn. Let's write one from scratch.</p>
KVM (Kernel-based Virtual Machine) is a Linux kernel module that turns the host into a hypervisor.</p>
We will use the KVM API to build software that runs a Virtual Machine. The industry uses the name VMM or Virtual Machine Monitor for such software — like Cloud Hypervisor</a> or Firecracker</a>.</p>

System Calls</h2>
KVM's API</a> is a set of `ioctl</code></a> system calls. Combined with` `mmap</code></a> for managing VM memory, these two system calls are all we need to build a VMM.</p>`
`In Rust we can call these system calls using the libc</a> crate, which provides raw FFI bindings to system libraries. Naturally these are unsafe</code> methods — we will need to ensure memory safety, such as by passing or reading data via valid pointers. Because "everything is a file" in Linux, we'll also need to ensure that we close files that are opened by these system calls.</p>`

KVM Version</h2>
First thing we want to check is if the system has a stable KVM API version, the constant value 12, otherwise the application should not run:</p>
use</span> std</span>::</span>{</span></span>
    error</span>::</span>Error</span>,</span></span>
    fs</span>::</span>OpenOptions</span>,</span></span>
    os</span>::</span>{</span>fd</span>::</span>AsRawFd</span>,</span> unix</span>::</span>fs</span>::</span>OpenOptionsExt</span>}</span>,</span></span>
}</span>;</span></span>
</span>
use</span> std</span>::</span>os</span>::</span>raw</span>::</span>{</span>c_uint</span>,</span> c_ulong</span>}</span>;</span></span>
</span>
const</span> KVM_VERSION</span>:</span> i32</span> =</span> 12</span>;</span></span>
const</span> KVMIO</span>:</span> c_uint</span> =</span> 0xAE</span>;</span></span>
const</span> KVM_GET_API_VERSION</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IO</span>(</span>KVMIO</span>,</span> 0x00</span>)</span>;</span></span>
</span>
fn</span> main</span>(</span>)</span> -></span> Result</span><</span>(</span>)</span>,</span> Box</span><</span>dyn</span> Error</span>></span>></span> {</span></span>
    let</span> file</span> =</span> OpenOptions</span>::</span>new</span>(</span>)</span></span>
        .</span>write</span>(</span>true</span>)</span></span>
        .</span>custom_flags</span>(</span>libc</span>::</span>O_RDWR</span> |</span> libc</span>::</span>O_CLOEXEC</span>)</span></span>
        .</span>open</span>(</span>"</span>/dev/kvm</span>"</span>)</span>?</span>;</span></span>
</span>
    let</span> kvm_fd</span> =</span> file</span>.</span>as_raw_fd</span>(</span>)</span>;</span></span>
</span>
    //</span></span>
    //</span> 1. Check KVM version, it not 12 refuse to run.</span></span>
    //</span></span>
</span>
    let</span> kvm_version</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>kvm_fd</span>,</span> KVM_GET_API_VERSION</span>,</span> 0</span>)</span> }</span>;</span></span>
</span>
    println!</span>(</span>"</span>kvm version </span>{</span>kvm_version</span>}</span>"</span>)</span>;</span></span>
</span>
    if</span> kvm_version</span> <</span> 0</span> {</span></span>
        let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
        println!</span>(</span>"</span>error getting kvm version</span>"</span>)</span>;</span></span>
        return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    if</span> kvm_version</span> !=</span> KVM_VERSION</span> {</span></span>
        eprintln!</span>(</span>"</span>current kvm version: </span>{</span>kvm_version</span>}</span>, required kvm version: </span>{</span>KVM_VERSION</span>}</span>"</span>)</span>;</span></span>
        return</span> Err</span>(</span>"</span>kvm version not supported</span>"</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    Ok</span>(</span>(</span>)</span>)</span></span>
}</span></span></code></pre>
Let's dissect this. First we open /dev/kvm</code> file for reading and writing and get the file descriptor as i32</code> that we need to pass to ioctl</code>.</p>
For ioctl</code>, the first argument is the file descriptor, the second is the operation code, and the third is a pointer to memory — its meaning depends on whether the operation reads or writes data.</p>
KVM operation codes can be created with methods that the kernel itself uses in ioctl.h</code></a> file. Fortunately libc</code> exposes them too with _IO</code>, _IOW</code> (if the operation writes data), and _IOR</code> (if the operation reads data) const functions.</p>
First we check if the ioctl</code> call itself was successful — by validating its return code is not negative. But it only tells us about success or failure. To get the actual error we need to use another library method errno</code></a>, which we can obtain by using std::io::Error::last_os_error()</code> method.</p>
Create a VM</h2>

Note:</strong> For brevity, from here onwards we only show new code. See the full source</a> for the complete program.</p>
</blockquote>
use</span> std</span>::</span>os</span>::</span>fd</span>::</span>FromRawFd</span>;</span></span>
</span>
const</span> KVM_CREATE_VM</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IO</span>(</span>KVMIO</span>,</span> 0x01</span>)</span>;</span></span>
</span>
</span>
//</span></span>
//</span> 2. Create A VM</span></span>
//</span></span>
</span>
let</span> vm_fd</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>kvm_fd</span>,</span> KVM_CREATE_VM</span>,</span> 0</span>)</span> }</span>;</span></span>
</span>
if</span> vm_fd</span> <</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>vm creation error</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
//</span> Own it so that fd is closed on drop</span></span>
let</span> vm_fd</span> =</span> unsafe</span> {</span> std</span>::</span>os</span>::</span>fd</span>::</span>OwnedFd</span>::</span>from_raw_fd</span>(</span>vm_fd</span>)</span> }</span>;</span></span></code></pre>
Here KVM_CREATE_VM</code> API returns a new file descriptor to manage this VM. This vm_fd</code> is just an integer just like kvm_fd</code> but with a the major difference between how these two are created - for kvm_fd</code> we used the Rust's std library to open a file and assigned it to let file</code>. The file</code> variable ensures that when it goes out of scope it gets Drop</code>-ed and file is closed.</p>
To achieve the same thing for vm_fd</code> integer, we construct OwnedFd</code> and shadow it by a variable of the same name. This way we take "ownership" of the VM file descriptor and when it goes out of scope, the Drop</code> on OwnedFd</code> will ensure the underlying file is closed.</p>
Create a VCPU</h2>
</span>
const</span> KVM_CREATE_VCPU</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IO</span>(</span>KVMIO</span>,</span> 0x41</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 3. Create A VCPU</span></span>
//</span></span>
</span>
let</span> vcpu_fd</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>vm_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span> KVM_CREATE_VCPU</span>,</span> 0</span>)</span> }</span>;</span></span>
</span>
if</span> vcpu_fd</span> <</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>vcpu creation error</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
//</span> Own it so that fd is closed on drop</span></span>
let</span> vcpu_fd</span> =</span> unsafe</span> {</span> std</span>::</span>os</span>::</span>fd</span>::</span>OwnedFd</span>::</span>from_raw_fd</span>(</span>vcpu_fd</span>)</span> }</span>;</span></span>
</span>
println!</span>(</span></span>
    "</span>kvm fd </span>{</span>kvm_fd</span>}</span>, vm fd: </span>{</span>}</span>, vcpu fd: </span>{</span>}</span>"</span>,</span></span>
    vm_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span></span>
    vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span></span>
)</span>;</span></span></code></pre>
To manage this VM, we use vm_fd</code> file descriptor to create a VCPU for it, and just like before here we have a new file descriptor vcpu_fd</code> for a new file, so we take ownership to ensure its closed when vcpu_fd</code> goes out of scope.</p>
Create Memory for VM</h2>
We need to create memory that will be virtual to VMM but will be seen as physical memory by VM.</p>
We create a memory mapping in the virtual address space of VMM with these characteristics: we want to read (PROT_READ</code>) and write (PROT_WRITE</code>) to this memory and it should not visible to other processes (MAP_PRIVATE</code>) and its contents need to be initialized to zero (MAP_ANONYMOUS</code>).</p>
const</span> VM_MEMORY</span>:</span> u64</span> =</span> 2</span> *</span> 4096</span>;</span> //</span> 2 blocks of 4KiB</span></span>
</span>
struct</span> Mmap</span> {</span></span>
    pub</span> ptr</span>:</span> *</span>mut</span> std</span>::</span>os</span>::</span>raw</span>::</span>c_void</span>,</span></span>
    pub</span> len</span>:</span> usize</span>,</span></span>
}</span></span>
</span>
impl</span> Drop</span> for</span> Mmap</span> {</span></span>
    fn</span> drop</span>(</span>&</span>mut</span> self</span>)</span> {</span></span>
        println!</span>(</span>"</span>calling libc:munmap</span>"</span>)</span>;</span></span>
        unsafe</span> {</span> libc</span>::</span>munmap</span>(</span>self</span>.</span>ptr</span>,</span> self</span>.</span>len</span>)</span> }</span>;</span></span>
    }</span></span>
}</span></span>
</span>
//</span></span>
//</span> 4. Create memory for guest</span></span>
//</span></span>
</span>
let</span> vm_memory_mmap</span> =</span> unsafe</span> {</span></span>
    libc</span>::</span>mmap</span>(</span></span>
        std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>,</span></span>
        VM_MEMORY</span> as</span> usize</span>,</span></span>
        libc</span>::</span>PROT_READ</span> |</span> libc</span>::</span>PROT_WRITE</span>,</span></span>
        libc</span>::</span>MAP_ANONYMOUS</span> |</span> libc</span>::</span>MAP_PRIVATE</span>,</span></span>
        -</span>1</span>,</span></span>
        0</span>,</span></span>
    )</span></span>
}</span>;</span></span>
</span>
if</span> vm_memory_mmap</span> ==</span> libc</span>::</span>MAP_FAILED</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>vm memory map failed</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
//</span> take ownership, so on drop munmap is called</span></span>
let</span> vm_memory_mmap</span> =</span> Mmap</span> {</span></span>
    ptr</span>:</span> vm_memory_mmap</span>,</span></span>
    len</span>:</span> VM_MEMORY</span> as</span> usize</span>,</span></span>
}</span>;</span></span></code></pre>
mmap</code> returns a pointer to mapped area - it is virtual address to the beginning of that memory. When our VMM program is done using this memory we need to delete the mapping using munmap</code></a> system call.</p>
For that we store pointer and the size of memory in Mmap</code> struct and implement Drop</code> for it - so when vm_memory_mmap</code> goes out of scope it automatically calls munmap</code>.</p>
Code that VM will execute</h2>
const</span> CODE</span>:</span> [</span>u8</span>;</span> 1</span>]</span> =</span> [</span>0xF4</span>]</span>;</span> //</span> HLT</span></span>
</span>
//</span></span>
//</span> 5. Copy code to guest's physical memory - that guest will execute</span></span>
//</span></span>
</span>
unsafe</span> {</span></span>
    std</span>::</span>ptr</span>::</span>copy_nonoverlapping</span>(</span>&</span>CODE</span> as</span> *</span>const</span> u8</span>,</span> vm_memory_mmap</span>.</span>ptr </span>as</span> *</span>mut</span> u8</span>,</span> 1</span>)</span>;</span></span>
}</span></span>
</span></code></pre>
Here we have some CODE</code> whose size is one byte and we copy it to the guest's memory. The CODE</code> is just single x86 instruction for HLT</code></a>.</p>
Setup Guest Memory</h2>
Now that our VMM has memory for the guest, we provide it to the KVM API to set it up as the guest's physical memory:</p>
</span>
const</span> KVM_SET_USER_MEMORY_REGION</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IOW</span>::</span><</span>kvm_userspace_memory_region</span>></span>(</span>KVMIO</span>,</span> 0x46</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 6. Setup guest's physical memory</span></span>
//</span></span>
</span>
let</span> vm_memory_addr</span> =</span> vm_memory_mmap</span>.</span>ptr </span>as</span> u64</span>;</span></span>
</span>
let</span> userspace_memory_region</span> =</span> kvm_userspace_memory_region</span> {</span></span>
    slot</span>:</span> 0</span>,</span></span>
    flags</span>:</span> 0</span>,</span></span>
    guest_phys_addr</span>:</span> 4096</span>,</span></span>
    memory_size</span>:</span> VM_MEMORY</span>,</span></span>
    userspace_addr</span>:</span> vm_memory_addr</span>,</span></span>
}</span>;</span></span>
</span>
let</span> ret</span> =</span> unsafe</span> {</span></span>
    libc</span>::</span>ioctl</span>(</span></span>
        vm_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span></span>
        KVM_SET_USER_MEMORY_REGION</span>,</span></span>
        &</span>userspace_memory_region</span>,</span></span>
    )</span></span>
}</span>;</span></span>
</span>
if</span> ret</span> !=</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>error setting user memory region</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span></code></pre>
The interesting thing here is we are assigning this memory to the start of the first byte after the 4KiB block in the guest's physical address space, so the CODE</code> we copied will be seen by the VM at the 4096th indexed byte location.</p>
Setup x86 CPU registers</h2>
CPU registers are what keep track of what a CPU is doing at any given time, and they are architecture-specific (x86, ARM, etc.).</p>
We want to setup x86 registers such that the first thing our VM executes is our CODE</code>.</p>
The instruction pointer register in the CPU stores the address of the next instruction to execute, and because we put our first and only instruction at 4096 — we set the rip</code> instruction pointer to it:</p>
</span>
const</span> KVM_SET_REGS</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IOW</span>::</span><</span>kvm_regs</span>></span>(</span>KVMIO</span>,</span> 0x82</span>)</span>;</span></span>
const</span> KVM_GET_SREGS</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IOR</span>::</span><</span>kvm_sregs</span>></span>(</span>KVMIO</span>,</span> 0x83</span>)</span>;</span></span>
const</span> KVM_SET_SREGS</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IOW</span>::</span><</span>kvm_sregs</span>></span>(</span>KVMIO</span>,</span> 0x84</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 7.1 Setup regular x86 cpu registers.</span></span>
//</span>   Set instruction pointer to start execution at 2nd' block of size 4096, because that's where we copied code</span></span>
//</span></span>
</span>
let</span> k_regs</span> =</span> kvm_regs</span> {</span></span>
    rip</span>:</span> 4096</span>,</span></span>
    rflags</span>:</span> 0x2</span>,</span></span>
    ..</span>Default</span>::</span>default</span>(</span>)</span></span>
}</span>;</span></span>
</span>
let</span> ret</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span> KVM_SET_REGS</span>,</span> &</span>k_regs</span>)</span> }</span>;</span></span>
</span>
if</span> ret</span> !=</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>error setting kvm_regs</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
//</span></span>
//</span> 7.2 Read default x86 special registers, and update them</span></span>
//</span></span>
</span>
let</span> mut</span> k_sregs</span> =</span> kvm_sregs</span>::</span>default</span>(</span>)</span>;</span></span>
let</span> ret</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span> KVM_GET_SREGS</span>,</span> &</span>k_sregs</span>)</span> }</span>;</span></span>
</span>
if</span> ret</span> !=</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>error getting kvm_sregs</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
k_sregs</span>.</span>cs</span>.</span>base </span>=</span> 0</span>;</span></span>
k_sregs</span>.</span>cs</span>.</span>selector </span>=</span> 0</span>;</span></span>
</span>
let</span> ret</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span> KVM_SET_SREGS</span>,</span> &</span>k_sregs</span>)</span> }</span>;</span></span>
</span>
if</span> ret</span> !=</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>error setting kvm_sregs</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span></code></pre>
For more about these registers, see the LWN article Using the KVM API</a>.</p>
KVM_RUN</h2>
Every VCPU has an associated kvm_run</code> data structure that the kernel uses to communicate with our VMM in userspace.
When we run our VCPU, the VM can exit at any time for various reasons (such as I/O). The reason is available in kvm_run.exit_reason</code>, which our VMM can handle (e.g., perform the requested I/O) before resuming the VM.</p>
KVM provides an API to get the size of kvm_run</code> data. We can then map memory of that size in our VMM, backed by the vcpu_fd</code> VCPU file.</p>
</span>
const</span> KVM_GET_VCPU_MMAP_SIZE</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IO</span>(</span>KVMIO</span>,</span> 0x04</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 8.1. Get the size of kvm_run</span></span>
//</span></span>
</span>
let</span> vcpu_mmap_size</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>kvm_fd</span>,</span> KVM_GET_VCPU_MMAP_SIZE</span>,</span> 0</span>)</span> }</span>;</span></span>
</span>
if</span> vcpu_mmap_size</span> <</span> 0</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>error getting vcpu mmap size: </span>{</span>vcpu_mmap_size</span>}</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
println!</span>(</span>"</span>vcpu mmap size: </span>{</span>vcpu_mmap_size</span>}</span> bytes</span>"</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 8.2 memory map the pointer to kvm_run data structure</span></span>
//</span></span>
</span>
let</span> kvm_run_mmap</span> =</span> unsafe</span> {</span></span>
    libc</span>::</span>mmap</span>(</span></span>
        std</span>::</span>ptr</span>::</span>null_mut</span>(</span>)</span>,</span></span>
        vcpu_mmap_size</span> as</span> usize</span>,</span></span>
        libc</span>::</span>PROT_READ</span> |</span> libc</span>::</span>PROT_WRITE</span>,</span></span>
        libc</span>::</span>MAP_SHARED</span>,</span></span>
        vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span></span>
        0</span>,</span></span>
    )</span></span>
}</span>;</span></span>
</span>
if</span> kvm_run_mmap</span> ==</span> libc</span>::</span>MAP_FAILED</span> {</span></span>
    let</span> last_os_error</span> =</span> std</span>::</span>io</span>::</span>Error</span>::</span>last_os_error</span>(</span>)</span>;</span></span>
    eprintln!</span>(</span>"</span>kvm_run mmap failed</span>"</span>)</span>;</span></span>
    return</span> Err</span>(</span>last_os_error</span>.</span>into</span>(</span>)</span>)</span>;</span></span>
}</span></span>
</span>
//</span> take ownership, so on drop munmap is called</span></span>
let</span> kvm_run_mmap</span> =</span> Mmap</span> {</span></span>
    ptr</span>:</span> kvm_run_mmap</span>,</span></span>
    len</span>:</span> vcpu_mmap_size</span> as</span> usize</span>,</span></span>
}</span>;</span></span></code></pre>
The mapping is MAP_SHARED</code> so updates are visible to VMM and carried through the underlying VCPU file.</p>
Run the VM</h2>
All that's left now is to run the VCPU and resolve any exits. Because we programmed our CODE</code> to halt on the first instruction, our VMM loop will receive that exit reason and stop:</p>
</span>
const</span> KVM_RUN</span>:</span> c_ulong</span> =</span> libc</span>::</span>_IO</span>(</span>KVMIO</span>,</span> 0x80</span>)</span>;</span></span>
</span>
//</span></span>
//</span> 9. Run VM until it executes hlt instruction in CODE</span></span>
//</span></span>
loop</span> {</span></span>
    let</span> ret</span> =</span> unsafe</span> {</span> libc</span>::</span>ioctl</span>(</span>vcpu_fd</span>.</span>as_raw_fd</span>(</span>)</span>,</span> KVM_RUN</span>,</span> 0</span>)</span> }</span>;</span></span>
</span>
    if</span> ret</span> !=</span> 0</span> {</span></span>
        eprintln!</span>(</span>"</span>KVM_RUN errored</span>"</span>)</span></span>
    }</span></span>
</span>
    let</span> k_run</span>:</span> &</span>kvm_run</span> =</span> unsafe</span> {</span> &</span>*</span>(</span>kvm_run_mmap</span>.</span>ptr </span>as</span> *</span>const</span> kvm_run</span>)</span> }</span>;</span></span>
</span>
    match</span> k_run</span>.</span>exit_reason </span>{</span></span>
        kvm_bindings</span>::</span>KVM_EXIT_HLT</span> =></span> {</span></span>
            println!</span>(</span>"</span>KVM_EXIT_HTL</span>"</span>)</span>;</span></span>
            return</span> Ok</span>(</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
        _</span> =></span> {</span></span>
            eprintln!</span>(</span>"</span>EXIT: </span>{</span>:?</span>}</span>"</span>,</span> k_run</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
Let's dissect the conversion of a raw pointer from C to a Rust reference for kvm_run</code>:</p>
Because we know the underlying pointer points to a valid memory layout containing kvm_run</code>, we perform the following operations on it:</p>

We cast it from a C type to a pointer type in Rust — because we only read from it, we cast it as kvm_run_mmap.ptr as *const kvm_run</code></li>
To convert this Rust pointer to a reference we use &*(...)</code> — *</code> dereferences the pointer and then &</code> immediately borrows it.</li>
</ol>
Congrats, we just ran our first VM!</p>
Closing Thoughts</h1>
This VMM is written using as few dependencies as possible — so we can stay as close to the kernel as possible and actually see what's going on.</p>
Those minimal dependencies are libc</code> for system calls and kvm-bindings</code> for architecture-specific data structures like kvm_regs</code>, kvm_run</code>, etc. Since the kvm-bindings</code></a> crate is generated by bindgen</code> using actual kernel code, that's as close as we can get.</p>
From here, you could extend this VMM to handle I/O port exits, run real-mode code, or even load a Linux kernel image.</p>
Full source code is available here: 64bit/miniHype</a></p>

Acknowledgements</h1>
This project was made possible by generous work of @ankane</a> who released feature to support Vectors of max dimension of 2000</a> in version `0.4.0</code> of pgvector</code> project. (The output dimension of latest OpenAI embedding model is 1536)</p>`

IPv6 in URLs</h2>
Colon in URL is used to separate the schema, hence IPv6 with colons is wrapped in `[]</code>. For example http://[beef::1]:8080</code></p>`

IPv6 in Firefox</h3>
</p>

[1]</a>: ~2.5 x 10^{21</sup> years = (2^{128-32</sup> secs) / 60 / 60 / 24 / 365</p>}}
[2]</a>: ~6.3 billion years = (2^{128</sup> / (2^{32</sup> x 400 x 10^{9</sup>)) secs / 60 / 60 / 24 / 365</p>}}}

How to do it</h1>
Because of many permutations of configuration options available, in the following I share the high level ideas.</p>

Pick a site framework</h2>
Pick your favourite site framework</a>. I picked Zola</a> because of my newly found love of Rust.</p>

1. Get a Domain Name.</h3>
I had already purchased my domain gigapotential.dev</a> on domains.google.com</a></p>

Automation using IaC</h1>
It would be nice to create all of these using a reusable IaC, but as of this day, there is an open issue to support Cloudflare Pages in terraform-provider-cloudflare</a>. And pulumi-cloudflare depends on same Terraform provider too</a>.</p>

Blog of Gigapotential

A minimal VMM in Rust with Apple Hypervisor

A minimal VMM in Rust with KVM

Song search in Rust using OpenAI

IPv4 to IPv6

Host a blog with minimal cost

Blog of Gigapotential

A minimal VMM in Rust with Apple Hypervisor

Create VM Memory</h2> For this, we need libc</code> for mmap</code> and munmap</code> system calls, so we add our only runtime dependency: cargo add libc</code>. We ask the system for read-write memory, but when mapping it to the hypervisor with hv_vm_map</code>, we make it read-write-execute.</p>

A minimal VMM in Rust with KVM

Closing Thoughts</h1> This VMM is written using as few dependencies as possible — so we can stay as close to the kernel as possible and actually see what's going on.</p>

Song search in Rust using OpenAI

How will we use embedding for song search?</h1> OpenAI provides models for creating embeddings from text. To create Embedding for Song data, we concatenate each field of Song</code> into one big text and pass it to OpenAI API as single input.</p>

Search queries</h1> Now that we have embeddings for the whole Kaggle dataset. Lets get 10 nearest neighbors for each query.</p> Here are some sample queries and their result, notice how it shows result with similar meaning as original query</p>

IPv4 to IPv6

Perspective</h1> Lets bring 2128</sup> to perspective.</p>

Shortened Representation</h2> Leading zeros can be ommitted. a001:a002:a003:a004:a005:000f:002f:03af</code> becomes a001:a002:a003:a004:a005:f:2f:3af</code></li> </ul> </li>

IPv6 in URLs</h2> Colon in URL is used to separate the schema, hence IPv6 with colons is wrapped in []</code>. For example http://[beef::1]:8080</code></p>

IPv6 using Curl</h3> ➜ ~ curl "http://[::ffff:127.0.0.1]:8888"</span></span> Hello from IPv6</span></span> ➜ ~ curl "http://[::ffff:7f00:1]:8888"</span></span> Hello from IPv6</span></span></code></pre>IPv6 in Firefox</h3> </p>

IPv6 in Firefox</h3> </p>

Host a blog with minimal cost

How to do it</h1> Because of many permutations of configuration options available, in the following I share the high level ideas.</p>

IPv6 in URLs</h2>
Colon in URL is used to separate the schema, hence IPv6 with colons is wrapped in `[]</code>. For example http://[beef::1]:8080</code></p>`

IPv6 in Firefox</h3>
</p>

[1]</a>: ~2.5 x 10^{21</sup> years = (2^{128-32</sup> secs) / 60 / 60 / 24 / 365</p>}}
[2]</a>: ~6.3 billion years = (2^{128</sup> / (2^{32</sup> x 400 x 10^{9</sup>)) secs / 60 / 60 / 24 / 365</p>}}}

How to do it</h1>
Because of many permutations of configuration options available, in the following I share the high level ideas.</p>