iommu_report_device_fault(9)

💖 iommu_report_device_fault(9) 💖

okay so bestie, welcome to the Kernel API Manual — this one's iommu_report_device_fault, and it's literally the "hey, something went wrong" hotline for IOMMU faults. let's get into it 🫶

---

✨ NAME ✨

iommu_report_device_fault — report a fault event to the device driver. yeah. that's the whole job. iconic honestly 💅

---

🌸 SYNOPSIS 🌸

int iommu_report_device_fault (struct device *dev , struct iopf_fault *evt );

---

🎀 ARGUMENTS 🎀

• dev — the device. the main character of this whole situation 🫶
• evt — the fault event data. the receipts, basically 📋

---

🦋 DESCRIPTION 🦋

so IOMMU drivers call this when they detect a fault — typically from inside a threaded IRQ handler (iykyk). and listen: if this function fails, then ops->page_response was called to complete evt if that was required. so the event doesn't just get left hanging, no cap. 💯

---

🚫 the PCI PASID Stop Marker situation 🚫

heads up: this module does not handle the PCI PASID Stop Marker. IOMMU drivers have to discard those themselves before reporting faults. a PASID Stop Marker (LRW = 0b100) doesn't expect a response — it may get generated when disabling a PASID (aka issuing a PASID stop request) by some PCI devices. so yeah, not our problem, but fr fr you need to handle it. 🙈

Here's the lore: the PASID stop request is issued by the device driver before unbind. once it completes, no page request gets generated for that PASID anymore, and the outstanding ones have already been pushed to the IOMMU (as per PCIe 4.0r1.0 - 6.20.1 and 10.4.1.2 - Managing PASID TLP Prefix Usage). some PCI devices will literally wait for all outstanding page requests to come back with a response before completing the PASID stop request. others are impatient and don't wait for page responses at all — instead they issue this Stop Marker that tells us when the PASID can be reallocated. two different personalities, same group chat 💀

---

✅ why discarding the Stop Marker is safe (bestie, trust) ✅

it is safe to discard the Stop Marker because it is an optimization. and here's the proof, in list form because we love structure:

a. Page requests, which are posted requests, have been flushed to the IOMMU when the stop request completes.

b. The IOMMU driver flushes all fault queues on unbind before freeing the PASID.

so even though the Stop Marker might be issued by the device after the stop request completes, outstanding faults will have been dealt with by the time the PASID is freed. no loose ends. slay. ✨

---

🧚 routing the fault 🧚

any valid page fault will eventually be routed to an iommu domain, and the page fault handler installed there will get called. the users of this handling framework should guarantee that:

• the iommu domain could only be freed after the device has stopped generating page faults (or the iommu hardware has been set to block the page faults), and
• the pending page faults have been flushed.

lowkey important: in case no page fault handler is attached, or no iopf params are set up, then ops->page_response gets called to complete the evt. don't forget about this one 🫶

Returns 0 on success, or an error in case of a bad/failed iopf setup. 😭

---

🌈 SEE ALSO 🌈

• Kernel file ./drivers/iommu/io-pgfault.c
• iopf_queue_flush_dev(9)
• iopf_group_response(9)
• iopf_group_dequeue(9)
• iopf_queue_discard_partial(9)
• iopf_queue_add_device(9)
• iopf_queue_remove_device(9)
• iopf_queue_alloc(9)
• iopf_queue_free(9)

go read those too, bestie, they're all connected 👑

---

and that's the whole page!! mwah 💋 this came from ./drivers/iommu, dated October 2026, and it's iommu_report_device_fault(9) — you're welcome, ily, now go report some faults responsibly 🎀💖