STRUCT IOMMU_IOAS_IOVA_RANGES(9)

📦 version 7.3.1, in nixpkgs unstable

✨ NAME ✨

struct iommu_ioas_iova_ranges — the ioctl(IOMMU_IOAS_IOVA_RANGES) bestie 💅

okay so real quick, this is a page from the Kernel API Manual (the truncated header situation reads struct iomm..._iova_ranges(9), and yes, that's the whole vibe — the header just gave up and started abbreviating 😭). Anyway. Let's get into it 🎀

🌸 SYNOPSIS 🌸

struct iommu_ioas_iova_ranges {
    __u32 size;
    __u32 ioas_id;
    __u32 num_iovas;
    __u32 __reserved;
    __aligned_u64 allowed_iovas;
    __aligned_u64 out_iova_alignment;
 };

🦋 Members 🦋

  • size — literally just sizeof(struct iommu_ioas_iova_ranges), that's it, that's the whole field 🫶
  • ioas_id — the IOAS ID you're reading ranges from, iykyk
  • num_iovas — input/output situation: total number of ranges in the IOAS, both going in and coming out 🔥
  • __reserved — must be 0, no cap, do not touch, do not be cute with it 💀
  • allowed_iovas — pointer to the output array of struct iommu_iova_range ⭐
  • out_iova_alignment — the minimum alignment required for mapping IOVA ✨

💖 Description 💖

So what this does: you query an IOAS for the ranges of allowed IOVAs. Mapping IOVA outside these ranges is not allowed 🙅‍♀️. num_iovas gets set to the total number of iovas, and allowed_iovas[] gets filled in as space permits.

The allowed ranges are dependent on the HW path the DMA operation takes, and they can change during the lifetime of the IOAS 🌀. A fresh empty IOAS will have a full range, and each attached device will narrow the ranges based on that device's HW restrictions. Detaching a device can widen the ranges back out (slay, reversible era 👑). Userspace should query ranges after every attach/detach to know what IOVAs are valid for mapping — like, don't guess, bestie, just ask.

On input num_iovas is the length of the allowed_iovas array. On output it is the total number of iovas filled in. The ioctl will return -EMSGSIZE and set num_iovas to the required value if num_iovas is too small 😭. In this case the caller should allocate a larger output array and re-issue the ioctl — glow-up and try again 💅.

out_iova_alignment returns the minimum IOVA alignment that can be given to IOMMU_IOAS_MAP/COPY. IOVA's must satisfy:

starting_iova % out_iova_alignment == 0
(starting_iova + length) % out_iova_alignment == 0

out_iova_alignment can be 1 indicating any IOVA is allowed 🎉. It cannot be higher than the system PAGE_SIZE — that's a hard limit, respect it 🌈.

🌟 SEE ALSO 🌟

  • Kernel file ./include/uapi/linux/iommufd.h
  • General ioctl format(9)
  • struct iommu_destroy(9)
  • struct iommu_ioas_alloc(9)
  • struct iommu_iova_range(9)
  • struct iommu_ioas_allow_iovas(9)
  • enum iommufd_ioas_map_flags(9)
  • struct iommu_ioas_map(9)
  • struct iommu_ioas_noiommu_get_pa(9)
  • struct iommu_ioas_map_file(9)
  • struct iommu_ioas_copy(9)
  • struct iommu_ioas_unmap(9)
  • enum iommufd_option(9)
  • enum iommufd_option_ops(9)
  • struct iommu_option(9)
  • enum iommufd_vfio_ioas_op(9)
  • struct iommu_vfio_ioas(9)
  • enum iommufd_hwpt_alloc_flags(9)
  • enum iommu_hwpt_vtd_s1_flags(9)
  • struct iommu_hwpt_vtd_s1(9)
  • struct iommu_hwpt_arm_smmuv3(9)
  • struct iommu_hwpt_amd_guest(9)
  • enum iommu_hwpt_data_type(9)
  • struct iommu_hwpt_alloc(9)
  • enum iommu_hw_info_vtd_flags(9)
  • struct iommu_hw_info_vtd(9)
  • enum iommu_hw_info_arm_smmuv3_flags(9)
  • struct iommu_hw_info_arm_smmuv3(9)
  • struct iommu_hw_info_tegra241_cmdqv(9)
  • struct iommu_hw_info_amd(9)
  • enum iommu_hw_info_type(9)
  • enum iommufd_hw_capabilities(9)
  • enum iommufd_hw_info_flags(9)
  • struct iommu_hw_info(9)
  • struct iommu_hwpt_set_dirty_tracking(9)
  • enum iommufd_hwpt_get_dirty_bitmap_flags(9)
  • struct iommu_hwpt_get_dirty_bitmap(9)
  • enum iommu_hwpt_invalidate_data_type(9)
  • enum iommu_hwpt_vtd_s1_invalidate_flags(9)
  • struct iommu_hwpt_vtd_s1_invalidate(9)
  • struct iommu_viommu_arm_smmuv3_invalidate(9)
  • struct iommu_hwpt_invalidate(9)
  • enum iommu_hwpt_pgfault_flags(9)
  • enum iommu_hwpt_pgfault_perm(9)
  • struct iommu_hwpt_pgfault(9)
  • enum iommufd_page_response_code(9)
  • struct iommu_hwpt_page_response(9)
  • struct iommu_fault_alloc(9)
  • enum iommu_viommu_type(9)
  • struct iommu_viommu_tegra241_cmdqv(9)
  • struct iommu_viommu_alloc(9)
  • struct iommu_vdevice_alloc(9)
  • struct iommu_ioas_change_process(9)
  • enum iommu_veventq_flag(9)
  • struct iommufd_vevent_header(9)
  • enum iommu_veventq_type(9)
  • struct iommu_vevent_arm_smmuv3(9)
  • struct iommu_vevent_tegra241_cmdqv(9)
  • struct iommu_veventq_alloc(9)
  • enum iommu_hw_queue_type(9)
  • struct iommu_hw_queue_alloc(9)
ngl that SEE ALSO list is a whole friend group 😭 but every single one of them is invited to the function, periodt 💜

and that's the whole page, bestie 🧚‍♀️ this one came from ./include/uapi/linux, dated October 2026 — yes, the future, we're ahead of schedule ✨ go forth and query your ranges responsibly 🍓💖

📦 where this page comes from