Method generate_sparse_areas

pci/src/vfio.rs:1551–1649

(
        caps: &[VfioRegionInfoCap],
        region_index: u32,
        region_start: u64,
        region_size: u64,
        vfio_msix: Option<&VfioMsix>,
    )

    }

    fn generate_sparse_areas(
        caps: &[VfioRegionInfoCap],
        region_index: u32,
        region_start: u64,
        region_size: u64,
        vfio_msix: Option<&VfioMsix>,
    ) -> Result<Vec<VfioRegionSparseMmapArea>, VfioPciError> {
        for cap in caps {
            match cap {
                VfioRegionInfoCap::SparseMmap(sparse_mmap) => return Ok(sparse_mmap.areas.clone()),
                VfioRegionInfoCap::MsixMappable => {
                    if !is_4k_aligned(region_start) {
                        error!(
                            "Region start address 0x{region_start:x} must be at least aligned on 4KiB"
                        );
                        return Err(VfioPciError::RegionAlignment);
                    }
                    if !is_4k_multiple(region_size) {
                        error!("Region size 0x{region_size:x} must be at least a multiple of 4KiB");
                        return Err(VfioPciError::RegionSize);
                    }

                    // In case the region contains the MSI-X vectors table or
                    // the MSI-X PBA table, we must calculate the subregions
                    // around them, leading to a list of sparse areas.
                    // We want to make sure we will still trap MMIO accesses
                    // to these MSI-X specific ranges. If these region don't align
                    // with pagesize, we can achieve it by enlarging its range.
                    //
                    // Using a BtreeMap as the list provided through the iterator is sorted
                    // by key. This ensures proper split of the whole region.
                    let mut inter_ranges = BTreeMap::new();
                    if let Some(msix) = vfio_msix {
                        if region_index == msix.cap.table_bir() {
                            let (offset, size) = msix.cap.table_range();
                            let offset = align_page_size_down(offset);
                            let size = align_page_size_up(size);
                            // MSI-X mmap region safety: when a device has a non page
                            // aligned MSI-X offset, fixup_msix_region() relocates MSI-X
                            // to the upper half of an enlarged virtual BAR, causing the
                            // offsets in msix.cap to exceed the physical BAR size. This
                            // check skips carving a hole, preventing invalid offsets from
                            // reaching the mmap path. With no holes,
                            // generate_sparse_areas() returns a single sparse region
                            // covering the entire physical BAR. The relocated MSI-X in
                            // the virtual BAR remains trapped because its upper half has
                            // no mmap backing. Exposing the physical MSI-X region through
                            // mmap is safe when the kernel advertises
                            // VFIO_REGION_INFO_CAP_MSIX_MAPPABLE. When MSI-X offsets are
                            // already page aligned, fixup_msix_region() does not relocate
                            // and this check is satisfied, so a hole is carved at the
                            // intended offset as before.
                            if offset < region_size {
                                inter_ranges.insert(offset, size);
                            }
                        }
                        if region_index == msix.cap.pba_bir() {
                            let (offset, size) = msix.cap.pba_range();