pci: expand sub-page VFIO BAR mmap to page size by saravan2 · Pull Request #7939 · cloud-hypervisor/cloud-hypervisor

saravan2 · 2026-03-31T17:32:57Z

On aarch64 with 64K host pages, VFIO passthrough of devices with sub-page BARs (e.g. 16K NVMe BAR0) crashes with EINVAL from KVM_SET_USER_MEMORY_REGION, which requires memory_size to be a multiple of the host page size.

Expand the mmap to page size instead of rejecting it, matching QEMU's approach. The kernel's vfio_pci_probe_mmaps() already verifies that sub-page BARs are page-aligned and reserves the remainder of the page, so this is safe.

The expanded mmap region will not overlap with the relocated MSI-X trap region because fixup_msix_region() ensures MSI-X relocation at >= page_size offset.

Validation

Host: aarch64, 64K pages (kernel 6.11), VFIO passthrough.
Device Under Test

Intel NVMe DC SSD [3DNAND, Sentinel Rock Controller] — 16K BAR0 with MSI-X in the same BAR.

  0006:01:00.0 Non-Volatile memory controller: Intel Corporation NVMe DC SSD
    Region 0: Memory at 630040010000 (64-bit, non-prefetchable) [size=16K]
    Capabilities: [50] MSI-X: Enable- Count=136 Masked-
            Vector table: BAR=0 offset=00002000
            PBA: BAR=0 offset=00003000

Launch

sudo /home/saravanand/cloud-hypervisor/target/aarch64-unknown-linux-musl/release/cloud-hypervisor \
    --cpus boot=4 \
    --memory size=0 \
    --memory-zone id=mem0,size=1G id=mem1,size=1G \
    --numa \
        guest_numa_id=0,cpus=[0-1],distances=[1@20,2@15],memory_zones=mem0 \
        guest_numa_id=1,cpus=[2-3],distances=[0@20,2@25],memory_zones=mem1 \
        guest_numa_id=2,device_id=nvme0,distances=[0@15,1@25] \
    --firmware /home/saravanand/test-generic-initiator/CLOUDHV_EFI.fd \
    --disk path=/home/saravanand/test-generic-initiator/ubuntu-24.04-server-cloudimg-arm64.raw \
           path=/home/saravanand/test-generic-initiator/seed.img \
    --device id=nvme0,path=/sys/bus/pci/devices/0006:01:00.0 \
    --net "tap=,mac=,ip=192.168.249.1,mask=255.255.255.0" \
    --serial tty \
    --console off

Functional

Guest enumerates NVMe controller and creates block device (/dev/nvme0n1)
Guest lspci shows doubled virtual BAR (128K) with MSI-X relocated to upper half
dmesg confirms 4/0/0 default/read/poll queues — full NVMe operation

Performance (fio 4K random read, io_uring, iodepth=64, numjobs=4, 60s, 3 runs)

ubuntu@ubuntu:~$ sudo fio \
    --name=randread \
    --ioengine=io_uring \
    --direct=1 \
    --bs=4k \
    --iodepth=64 \
    --numjobs=4 \
    --rw=randread \
    --size=1G \
    --runtime=60 \
    --time_based \
    --filename=/dev/nvme0n1 \
    --group_reporting

Median IOPS: 747,589 — no regression from baseline Pre-#7904

phip1611

I'm not a PCI expert but I think the changes are good - thanks for the contribution! I'm worried about code readability and think we can do a little better here

saravan2 · 2026-04-11T02:44:39Z

Before #7904, generate_sparse_areas() read the relocated MSI-X offsets from
msix.cap (already modified by fixup_msix_region()).

For 16K BAR device on a 64K page host:

fixup_msix_region() relocates MSI-X from 0x2000 to 0x10000 (upper half of a 128K virtual BAR)
generate_sparse_areas(region_size=0x4000) inserts a hole at
align_page_size_down(0x10000) = 0x10000 — beyond the physical 16K BAR
The hole-carving loop sees range_offset (0x10000) > current_offset (0) and creates
a sparse area {offset: 0, size: 0x10000} = 64K
This 64K sparse area exceeds the physical BAR (16K) but happens to equal the host page
size. The kernel's vfio_pci_probe_mmaps() reserves the full page for sub-page BARs,
so mmap(64K) succeeds. KVM_SET_USER_MEMORY_REGION(size=64K) succeeds because 64K
is page-aligned

The out-of-range MSI-X hole accidentally inflated the sparse area to exactly page size,
masking the sub-page BAR problem.

#7904 added an offset < region_size guard to skip out-of-range holes. Now
generate_sparse_areas() correctly produces a 16K sparse area matching the physical BAR.
But KVM_SET_USER_MEMORY_REGION rejects 16K with EINVAL because it is not a multiple
of the 64K host page size. Passthrough fails at VM boot.

This patch explicitly expands sub-page sparse area mmaps to host page size in
map_mmio_regions(), and ensures fixup_msix_region() makes the virtual BAR lower half
at least one page so the expanded KVM slot cannot overlap the relocated MSI-X trap region.
The result is the same 64K mmap as the accidental pre-#7904 path, but achieved correctly.

likebreath

Thank you for the contribution with detailed comments and performance regression test.

Some comments below. Please also don't forget to update the commit message and comments added.

saravan2 · 2026-04-12T01:21:09Z

Some comments below. Please also don't forget to update the commit message and comments added.

Addressed all of them. Updated comments, commit message and PR description. Thanks for your review.

rbradford · 2026-04-12T10:04:57Z

+                            );
+                            return Err(VfioPciError::MmapArea);
+                        }
+                        info!(


nit: Include the BAR ID (region.index) here and in the error above for easier debugging?

Added region.index information to the messages.

On aarch64 with 64K host pages, VFIO passthrough of devices with sub-page BARs (e.g. 16K NVMe BAR0) crashes with EINVAL from KVM_SET_USER_MEMORY_REGION, which requires memory_size to be a multiple of the host page size. Expand the mmap to page size instead of rejecting it, matching QEMU's approach. The kernel's vfio_pci_probe_mmaps() already verifies that sub-page BARs are page-aligned and reserves the remainder of the page, so expansion is safe at offset 0. Reject sub-page sparse areas at non-zero offsets where this guarantee does not apply. The expanded mmap region will not overlap with the relocated MSI-X trap region because fixup_msix_region() ensures MSI-X relocation at >= page_size offset. Signed-off-by: Saravanan D <saravanand@crusoe.ai>

phip1611 reviewed Mar 31, 2026

View reviewed changes

Comment thread pci/src/vfio.rs Outdated

Comment thread pci/src/vfio.rs Outdated

saravan2 force-pushed the 64KiB branch from 1ca33d8 to 7904c55 Compare April 10, 2026 06:28

phip1611 approved these changes Apr 10, 2026

View reviewed changes

saravan2 marked this pull request as ready for review April 11, 2026 00:55

saravan2 requested a review from a team as a code owner April 11, 2026 00:55

saravan2 force-pushed the 64KiB branch from 7904c55 to 8297950 Compare April 11, 2026 01:23

saravan2 force-pushed the 64KiB branch from 8297950 to 6972536 Compare April 11, 2026 02:47

likebreath reviewed Apr 11, 2026

View reviewed changes

Comment thread pci/src/vfio.rs Outdated

Comment thread pci/src/vfio.rs

Comment thread pci/src/vfio.rs Outdated

saravan2 force-pushed the 64KiB branch from 6972536 to f1f5d79 Compare April 12, 2026 01:04

saravan2 requested a review from likebreath April 12, 2026 01:23

rbradford approved these changes Apr 12, 2026

View reviewed changes

saravan2 force-pushed the 64KiB branch from f1f5d79 to 8178ebf Compare April 12, 2026 10:08

rbradford approved these changes Apr 12, 2026

View reviewed changes

rbradford enabled auto-merge April 12, 2026 10:44

rbradford added this pull request to the merge queue Apr 12, 2026

Merged via the queue into cloud-hypervisor:main with commit 23a980c Apr 12, 2026
37 of 38 checks passed

saravan2 deleted the 64KiB branch April 17, 2026 07:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

pci: expand sub-page VFIO BAR mmap to page size#7939

pci: expand sub-page VFIO BAR mmap to page size#7939
rbradford merged 1 commit intocloud-hypervisor:mainfrom
saravan2:64KiB

saravan2 commented Mar 31, 2026 •

edited

Loading

Uh oh!

phip1611 left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

saravan2 commented Apr 11, 2026 •

edited

Loading

Uh oh!

likebreath left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saravan2 commented Apr 12, 2026

Uh oh!

rbradford Apr 12, 2026

Uh oh!

saravan2 Apr 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

saravan2 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phip1611 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

saravan2 commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

likebreath left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saravan2 commented Apr 12, 2026

Uh oh!

rbradford Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

saravan2 Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

saravan2 commented Mar 31, 2026 •

edited

Loading

phip1611 left a comment •

edited

Loading

saravan2 commented Apr 11, 2026 •

edited

Loading