Home

hyperv-virtiofs Wiki

hyperv-virtiofs is a Windows-only hyperv_virtiofs.dll that lets a host process attach OpenVMM virtio-fs devices to HCS / Hyper-V guests through Host Device Virtualization (HDV). In practice, it is virtiofsd for Hyper-V: a host directory becomes a normal virtiofs.ko mount inside a Linux guest without 9p and without guest kernel patches.

The public product surface is intentionally small: the C ABI in include/hyperv_virtiofs.h. Everything else is implementation detail, test rig, or reusable HDV transport machinery.

Current Status

• ABI v2 is shipped and tested end-to-end through a live Rocky Linux 10 guest.
• Shares are hot-added to a running VM: one hvfs_share equals one virtio-fs device equals one host directory.
• Multiple shares can coexist on one compute system through one registered HDV device host.
• Live share removal is best-effort only on current Windows builds. hvfs_remove_share usually returns HVFS_ERR_UNSUPPORTED, releases host-side resources, and the guest-visible device is reclaimed when the VM is recycled.
• Read-only shares are not yet enforced. Passing "ro": true returns HVFS_ERR_NOT_IMPLEMENTED rather than silently mounting read-write.
• Hosted GitHub CI covers build, clippy, formatting, unit tests, and generated-header freshness. The live VM ladder requires a Hyper-V-capable Windows host.

Read This First

If you are integrating the DLL into a host process, start with:

1. C ABI Usage
2. Integration Guide
3. Gotchas and Platform Constraints
4. Testing and Diagnostics

If you are changing the implementation, start with:

1. Architecture
2. Goals and Roadmap
3. ABI Change Checklist

Minimum Lifecycle

if (hvfs_abi_version() != HVFS_ABI_VERSION) {
    /* refuse to load */
}

hvfs_host *host = NULL;
int32_t rc = hvfs_host_open(
    hcs_system_id,
    "{\"memory_mb\":512}",
    &host);

/* caller starts the compute system */

hvfs_share *share = NULL;
rc = hvfs_add_share(
    host,
    "{\"tag\":\"ws\",\"path\":\"C:\\\\host\\\\dir\","
    "\"instance_id\":\"c1c1c1c1-3333-4333-8333-333333333333\"}",
    &share);

/* guest mounts: mount -t virtiofs ws /mnt/ws */

rc = hvfs_remove_share(share); /* often HVFS_ERR_UNSUPPORTED; handle is freed */
hvfs_host_close(host);

The order matters: hvfs_host_open happens before VM start, hvfs_add_share happens after VM start, and hvfs_host_close happens before the caller stops/deletes the compute system.

Repository Links

• Source repository: jlagedo/hyperv-virtiofs
• Public ABI header: include/hyperv_virtiofs.h
• C example: examples/c/main.c
• Go binding pattern: examples/go/main.go
• Original design notes: docs/share-abi.md, docs/testing.md, docs/roadmap.md