AI Trajectory

null

{
  "EnableConfigs": null,
  "FocusSymbols": [],
  "KMSANReasoning": "",
  "NeedsKMSAN": false,
  "Reasoning": "The patch only adds documentation for VFIO selftests (Documentation/driver-api/vfio-selftests.rst, Documentation/driver-api/index.rst) and updates the MAINTAINERS file. No kernel executable code or headers are modified.",
  "WorthFuzzing": false
}

null

{
  "PatchDiff": "commit f60a2a74c5889ba20740e39d5cb2394b81769f20\nAuthor: syz-cluster \u003ctriage@syzkaller.com\u003e\nDate:   Sat Sep 5 04:09:33 2026 +0000\n\n    syz-cluster: applied patch under review\n\ndiff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst\nindex eaf7161ff9578..630f33287bc0c 100644\n--- a/Documentation/driver-api/index.rst\n+++ b/Documentation/driver-api/index.rst\n@@ -47,6 +47,7 @@ of interest to most developers working on device drivers.\n    vfio-mediated-device\n    vfio\n    vfio-pci-device-specific-driver-acceptance\n+   vfio-selftests\n \n Bus-level documentation\n =======================\ndiff --git a/Documentation/driver-api/vfio-selftests.rst b/Documentation/driver-api/vfio-selftests.rst\nnew file mode 100644\nindex 0000000000000..9d39a22519d6a\n--- /dev/null\n+++ b/Documentation/driver-api/vfio-selftests.rst\n@@ -0,0 +1,252 @@\n+.. SPDX-License-Identifier: GPL-2.0\n+\n+==============\n+VFIO Selftests\n+==============\n+\n+VFIO selftests are built on top of the kernel's selftests framework and are\n+located in ``tools/testing/selftests/vfio``.\n+\n+VFIO selftests enable kernel developers to write and run tests that take the\n+form of userspace programs that interact with VFIO and IOMMUFD uAPIs. VFIO\n+selftests can be used to write functional tests for new features, regression\n+tests for bugs, and performance tests for optimizations.\n+\n+These tests are designed to interact with real PCI devices, i.e. they do not\n+rely on mocking out or faking any behavior in the kernel. This allows the tests\n+to exercise not only VFIO but also IOMMUFD, the IOMMU driver, interrupt\n+remapping, IRQ handling, etc.\n+\n+Running Tests\n+=============\n+\n+Running VFIO selftests requires a device bound to the ``vfio-pci`` driver.\n+There are scripts in ``tools/testing/selftests/vfio/scripts/`` to help with\n+setting one up.\n+\n+Picking a Device\n+----------------\n+\n+Some VFIO selftests require a device with a supported driver implementation in\n+the selftests library (see `Driver Framework`_), while other tests (such as\n+basic PCI configuration space or reset tests) can use any arbitrary PCI device.\n+\n+This section will be expanded in the future to guide developers on how to find\n+a device with a supported driver. In the meantime, the selftests library\n+includes driver support for the following devices:\n+\n+- Intel IGB Gigabit Ethernet controllers\n+- Intel IOAT (I/O Acceleration Technology) DMA engines\n+- Intel DSA (Data Streaming Accelerator)\n+- NVIDIA Falcon engines (found in many NVIDIA GPUs, e.g., GTX 1080 or RTX 2080)\n+\n+Note that using Intel DSA devices requires setting the module parameter\n+``vfio_pci.disable_denylist=Y`` to allow ``vfio-pci`` to bind to DSA devices.\n+\n+Setting up Devices\n+------------------\n+\n+.. code-block:: sh\n+\n+    tools/testing/selftests/vfio/scripts/setup.sh 0000:01:00.0\n+\n+The script handles unbinding the device from its current driver and binding it\n+to ``vfio-pci``. Metadata about this device is stored in\n+``/tmp/vfio-selftests-devices`` so that the device can be cleaned up later\n+(bound back to its original driver).\n+\n+Execution\n+---------\n+\n+VFIO selftests expect the PCI device BDF string as their final command-line\n+argument. e.g.\n+\n+.. code-block:: sh\n+\n+    tools/testing/selftests/vfio/vfio_pci_device_test 0000:01:00.0\n+\n+Alternatively, the PCI device BDF can be passed via the ``VFIO_SELFTESTS_BDF``\n+environment variable, which can be useful when running all tests:\n+\n+.. code-block:: sh\n+\n+\texport VFIO_SELFTESTS_BDF=0000:01:00.0\n+\tmake -C tools/testing/selftests TARGETS=vfio install\n+\ttools/testing/selftests/kselftest_install/run_kselftest.sh -c vfio\n+\n+Cleanup\n+-------\n+\n+.. code-block:: sh\n+\n+    tools/testing/selftests/vfio/scripts/cleanup.sh\n+\n+This script handles unbinding all previously setup devices from ``vfio-pci``\n+and binding them back to their original driver. Specific devices can be cleaned\n+up by passing their BDF string to the cleanup script.\n+\n+Writing Tests\n+=============\n+\n+VFIO selftests leverage the ``kselftest_harness.h`` macros to structure setup\n+and teardown scenarios. A basic test involves:\n+\n+1. Declaring a test FIXTURE containing the device and IOMMU state.\n+2. Generating test variants that span the different IOMMU modes utilizing\n+   ``FIXTURE_VARIANT_ADD_ALL_IOMMU_MODES()``.\n+3. Initializing the device and binding the default driver ops.\n+\n+For a complete example of writing a VFIO selftest, refer to\n+``tools/testing/selftests/vfio/vfio_pci_device_test.c``.\n+\n+VFIO Selftests Library (libvfio)\n+================================\n+\n+The selftests directory contains a helper library compiled from the ``lib/``\n+subdirectory. It provides structures and helper functions to handle standard\n+operations like opening VFIO devices, creating VFIO containers, and interacting\n+with VFIO and IOMMUFD.\n+\n+All VFIO selftests have libvfio linked in by default. Tests can access the\n+library by including ``\u003clibvfio.h\u003e``.\n+\n+Core Objects\n+------------\n+\n+The VFIO selftests framework revolves around two distinct core objects:\n+``struct iommu`` and ``struct vfio_pci_device``. It is important to understand\n+the distinction and relationship between them:\n+\n+- ``struct iommu`` represents an IOMMU domain and the API used to program it\n+  (e.g. legacy VFIO Type1 vs IOMMUFD). It is responsible for managing the I/O\n+  address space, handling DMA mappings, and translating between host virtual\n+  addresses (HVA) and IO virtual addresses (IOVA).\n+\n+- ``struct vfio_pci_device`` represents a single PCI device. It encapsulates\n+  the VFIO device file descriptor, handles access to the PCI configuration\n+  space, manages memory-mapped BARs, and drives device interrupts.\n+\n+A typical test initializes an IOMMU instance first, then passes it when\n+initializing one or more PCI devices, linking the devices to the shared IOMMU\n+domain.\n+\n+``struct iommu``\n+^^^^^^^^^^^^^^^^\n+\n+The ``struct iommu`` abstracts away the complexity of managing VFIO containers,\n+IOMMU groups, and IOMMUFD contexts. A test allocates its IOMMU handle using\n+``iommu_init()`` passing one of the supported IOMMU modes:\n+\n+.. code-block:: c\n+\n+    struct iommu *iommu = iommu_init(MODE_IOMMUFD);\n+    ...\n+    iommu_cleanup(iommu);\n+\n+The selftest framework is designed to work uniformly across all standard kernel\n+IOMMU APIs. The defined modes (in ``iommu.h``) include:\n+\n+- ``MODE_VFIO_TYPE1_IOMMU``\n+- ``MODE_VFIO_TYPE1V2_IOMMU``\n+- ``MODE_IOMMUFD_COMPAT_TYPE1``\n+- ``MODE_IOMMUFD_COMPAT_TYPE1V2``\n+- ``MODE_IOMMUFD``\n+\n+VFIO selftests can replicate their test cases across all possible IOMMU modes\n+using FIXTURE_VARIANT_ADD_ALL_IOMMU_MODES() to ensure kernel IOMMU APIs remain\n+compatible.\n+\n+``struct vfio_pci_device``\n+^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+A PCI device is represented as a ``struct vfio_pci_device``. The device\n+representation is initialized using ``vfio_pci_device_init()``, which takes a\n+target BDF string, opens the device in VFIO, and binds it to an existing\n+``struct iommu`` instance:\n+\n+.. code-block:: c\n+\n+    struct vfio_pci_device *device = vfio_pci_device_init(device_bdf, iommu);\n+    ...\n+    vfio_pci_device_cleanup(device);\n+\n+``struct iova_allocator``\n+^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+To facilitate DMA mappings without hardcoding IOVAs (IO virtual addresses) that\n+might conflict with reserved platform address ranges, the library provides a\n+``struct iova_allocator``.\n+\n+The IOVA allocator queries the underlying IOMMU (via ``struct iommu``) for its\n+valid target IOVA ranges. Tests can safely carve out unique contiguous chunks\n+of IOVA space for device DMA by repeatedly calling:\n+\n+.. code-block:: c\n+\n+    struct iova_allocator *allocator = iova_allocator_init(iommu);\n+    iova_t addr = iova_allocator_alloc(allocator, size);\n+\n+Driver Framework\n+----------------\n+\n+The primary goal of VFIO selftests is to verify the correctness of the kernel\n+code handling VFIO devices, including VFIO core, IOMMUFD, IOMMU drivers, page\n+pinning, DMA mapping/unmapping, interrupt remapping, and IRQ delivery.\n+\n+Because different physical devices have vastly different programming interfaces\n+for triggering work, the selftests library implements a standard driver\n+framework.  This framework abstracts diverse hardware endpoints (such as Intel\n+IGB, IOAT, or DSA) behind a uniform interface, allowing tests to provoke a\n+broad range of devices to generate DMA operations and interrupts in a\n+standardized manner.\n+\n+By exercising DMA and interrupts with real endpoints, tests can thoroughly\n+stress and validate the underlying kernel paths, such as IOMMU page table\n+management, dirty page tracking, Device TLB and IOTLB invalidations, and\n+interrupt delivery under authentic hardware conditions.\n+\n+All endpoint driver implementations populate a common set of operations defined\n+in ``struct vfio_pci_driver_ops``:\n+\n+- ``probe()``: Validate whether the driver supports the current PCI device\n+  (e.g. matching vendor/device IDs).\n+- ``init()``: Set up specific control registers or ring-buffer data structures.\n+- ``remove()``: Clean up structures before destruction.\n+- ``memcpy_start()``: Initiate DMA copies via the device.\n+- ``memcpy_wait()``: Poll and wait until previously initiated copies complete\n+  safely.\n+- ``send_msi()``: Provoke the device to signal an MSI interrupt.\n+\n+Tests are required to set up a dedicated DMA region for the driver to use\n+within ``struct vfio_pci_driver`` to serve as the driver's main memory\n+allocation region (e.g. used for in-memory descriptor rings and hardware\n+buffers). Tests must provision and map this DMA region before completing driver\n+initialization.\n+\n+For a complete example of interacting with the driver framework from a test\n+perspective, refer to ``tools/testing/selftests/vfio/vfio_pci_driver_test.c``.\n+\n+When contributing a new driver implementation to the selftests library, the\n+primary acceptance criteria is that ``vfio_pci_driver_test`` passes using the\n+new driver and target device.\n+\n+Integration with KVM Selftests\n+------------------------------\n+\n+libvfio is not strictly limited to VFIO selftests, it is also leveraged within\n+KVM selftests (``tools/testing/selftests/kvm/``). KVM selftests build their own\n+copy of libvfio and link against it, enabling libvfio to be used in KVM\n+selftests.\n+\n+This integration enables testing the interaction between KVM and VFIO and\n+IOMMUFD. For example, testing the end-to-end delivery of device interrupts into\n+running vCPUs.\n+\n+Contribution Guidelines\n+=======================\n+\n+- Prefer the shortlog prefix ``vfio: selftests: ...`` for commits that modify\n+  files in ``tools/testing/selftests/vfio/``.\n+- Follow the Coding Style, Comments, Changelogs, and Function References\n+  guidelines from the\n+  :doc:`KVM x86 maintainers handbook \u003c/process/maintainer-kvm-x86\u003e`.\ndiff --git a/MAINTAINERS b/MAINTAINERS\nindex 806bd2d80d153..ba174dd8ba1b8 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -28396,6 +28396,7 @@ VFIO SELFTESTS\n M:\tDavid Matlack \u003cdmatlack@google.com\u003e\n L:\tkvm@vger.kernel.org\n S:\tMaintained\n+F:\tDocumentation/driver-api/vfio-selftests.rst\n F:\ttools/testing/selftests/vfio/\n \n VFIO VIRTIO PCI DRIVER\n"
}

core

null

{
  "EnableConfigs": null,
  "FocusSymbols": [],
  "Reasoning": "The patch only adds documentation for VFIO selftests (Documentation/driver-api/vfio-selftests.rst, Documentation/driver-api/index.rst) and updates the MAINTAINERS file. No kernel executable code or headers are modified.",
  "WorthFuzzing": false
}

You are an expert Linux kernel maintainer and security engineer.
Your job is to review a provided patch series and evaluate whether it warrants fuzzing with syzkaller.

IMPORTANT: The changes have ALREADY been applied and committed as the HEAD commit in
your workspace. Do NOT rely on internal assumptions. You must actively use your code access
tools to inspect the actual source code, callers, and surrounding context.

================================================================================
1. CORE TRIAGE PHILOSOPHY
================================================================================
The goal of patch fuzzing is to discover crashes, regressions, exposed latent bugs,
and newly triggered assertions introduced by the patch series.

- REACHABILITY IS THE PRIMARY GATE:
  Fuzzing can only discover bugs in code that can actually execute in standard virtualized
  environments (GCE or QEMU, utilizing software-emulated devices like USB gadgets, netdev, tun/tap).
  If the modified code is structurally unreachable (see Section 2), it MUST NOT be fuzzed,
  regardless of whether it adds assertions or complex logic.

- DO NOT BLINDLY TRUST "NO FUNCTIONAL CHANGE" (NFCI) OR "REFACTORING" CLAIMS:
  Patch authors routinely label changes as "cleanups", "refactorings", or state
  "No functional change intended". Do NOT take these claims at face value.
  Code refactorings that rearrange logic, introduce helper functions, or alter state management
  in core subsystems frequently introduce subtle semantic shifts or uncover latent kernel bugs.
  If reachable executable code is modified or refactored, it MUST be fuzzed.

- NEW OR MODIFIED ASSERTIONS IN REACHABLE CODE MUST BE FUZZED:
  When a patch introduces or modifies runtime checks or assertions (e.g., WARN_ON*, VM_WARN_ON*,
  BUG_ON*, lockdep_assert*) in reachable code paths, it enforces new or stricter invariants.
  Even if the author believes the invariant always holds, fuzzing is essential to verify whether
  an unusual sequence of operations can violate it.

================================================================================
2. WHEN TO RETURN WorthFuzzing=false (NEGATIVE CRITERIA)
================================================================================
Return WorthFuzzing=false ONLY IF all modified code falls strictly into one or more of these categories:

- Non-kernel and non-executable changes:
  * Modifications to Documentation/, comments, or spelling fixes.
  * User-space directories, self-tests, samples, or scripts (e.g., tools/, samples/, scripts/, usr/)
    that do not affect the compiled kernel image (vmlinux) or kernel modules.
  * Purely decorative logging (e.g., message strings in pr_err, printk, dev_info) or tracepoints
    that do not alter control flow or data structures.
  * Build system or Kconfig changes that do not alter compiled C logic.
- Structurally unreachable hardware:
  * Vendor-specific PCIe switches, SmartNICs, or GPU drivers (e.g., mlxsw, pds_core, qed,
    ionic, amdgpu) requiring physical ASIC/PCIe cards not emulated in standard QEMU.
- Unreachable execution paths:
  * Driver teardown callbacks (.remove, .shutdown, pci_unregister_driver) executed only during
    physical PCI hot-unplug or manual sysfs driver unbinding.
  * Code paths exclusive to architectures other than the target architecture.

================================================================================
3. WHEN TO RETURN WorthFuzzing=true (POSITIVE CRITERIA)
================================================================================
Return WorthFuzzing=true whenever the patch touches reachable executable code, including:
- Core Subsystems:
  * Any logic modifications in memory management (mm/), synchronization/locking (kernel/locking/),
    BPF, scheduler, core networking, VFS, or syscall handling.
- Refactorings and Code Cleanups:
  * Any restructuring of reachable data structures, helper abstractions, or algorithm flows.
- Runtime Assertions and Defensive Checks:
  * Any introduction or alteration of assertions (WARN_ON*, VM_WARN_ON*, BUG_ON*, etc.) in reachable paths.
- Reachable Drivers and Protocols:
  * Drivers accessible via virtual buses (virtio, USB gadget, loopback, netlink, binder, sockets, etc.).

================================================================================
4. EXTRACTING FocusSymbols (PREVENTING DILUTION)
================================================================================
When WorthFuzzing=true, you must extract specific kernel functions into FocusSymbols to guide the fuzzer:

- AVOID UBIQUITOUS LIFECYCLE HOT-PATHS:
  Do NOT list generic, ubiquitous functions called by almost every program in the corpus
  (including, but not limited to: general memory allocators and deallocators, page fault
  and trap handlers, or core synchronization primitives; this is not an exhaustive list).
  Listing ubiquitous functions causes the fuzzer to classify thousands of unrelated tests as "focused",
  which severely dilutes fuzzing effort away from the actual changes.

- TARGET SPECIFIC FEATURE LOGIC AND ENTRYPOINTS:
  List functions that specifically implement the logic being added or altered, or direct API entrypoints
  for the subsystem feature under review.

- HANDLING STATIC INLINE FUNCTIONS IN HEADERS (.h):
  Compiler-inlined static functions (such as static inlines in mm/*.h or include/linux/*.h) lack
  distinct symbol addresses in vmlinux and cannot be targeted directly by symbol coverage filters.
  If the changes are primarily in static inline helpers, identify non-static, feature-specific caller
  functions in .c files that exercise them (avoiding ubiquitous lifecycle wrappers).

================================================================================
5. IDENTIFYING EnableConfigs
================================================================================
Identify any specific CONFIG_ options required to properly compile and reach the modified code:
- Inspect Kconfig files and #ifdef guards; do not make assumptions.
- Check "depends on" lines in Kconfig to include any non-standard parent subsystem configs needed.
- Strip any 'CONFIG_' prefix (e.g., return "NET_IPV4" instead of "CONFIG_NET_IPV4").
Prefer calling several tools at the same time to save round-trips.


Use set-results tool to provide results of the analysis.
It must be called exactly once before the final reply.
Ignore results of this tool.

Target architecture: amd64

For your convenience, here is the diff of the changes:
commit f60a2a74c5889ba20740e39d5cb2394b81769f20
Author: syz-cluster <triage@syzkaller.com>
Date:   Sat Sep 5 04:09:33 2026 +0000

    syz-cluster: applied patch under review

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index eaf7161ff9578..630f33287bc0c 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -47,6 +47,7 @@ of interest to most developers working on device drivers.
    vfio-mediated-device
    vfio
    vfio-pci-device-specific-driver-acceptance
+   vfio-selftests
 
 Bus-level documentation
 =======================
diff --git a/Documentation/driver-api/vfio-selftests.rst b/Documentation/driver-api/vfio-selftests.rst
new file mode 100644
index 0000000000000..9d39a22519d6a
--- /dev/null
+++ b/Documentation/driver-api/vfio-selftests.rst
@@ -0,0 +1,252 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+VFIO Selftests
+==============
+
+VFIO selftests are built on top of the kernel's selftests framework and are
+located in ``tools/testing/selftests/vfio``.
+
+VFIO selftests enable kernel developers to write and run tests that take the
+form of userspace programs that interact with VFIO and IOMMUFD uAPIs. VFIO
+selftests can be used to write functional tests for new features, regression
+tests for bugs, and performance tests for optimizations.
+
+These tests are designed to interact with real PCI devices, i.e. they do not
+rely on mocking out or faking any behavior in the kernel. This allows the tests
+to exercise not only VFIO but also IOMMUFD, the IOMMU driver, interrupt
+remapping, IRQ handling, etc.
+
+Running Tests
+=============
+
+Running VFIO selftests requires a device bound to the ``vfio-pci`` driver.
+There are scripts in ``tools/testing/selftests/vfio/scripts/`` to help with
+setting one up.
+
+Picking a Device
+----------------
+
+Some VFIO selftests require a device with a supported driver implementation in
+the selftests library (see `Driver Framework`_), while other tests (such as
+basic PCI configuration space or reset tests) can use any arbitrary PCI device.
+
+This section will be expanded in the future to guide developers on how to find
+a device with a supported driver. In the meantime, the selftests library
+includes driver support for the following devices:
+
+- Intel IGB Gigabit Ethernet controllers
+- Intel IOAT (I/O Acceleration Technology) DMA engines
+- Intel DSA (Data Streaming Accelerator)
+- NVIDIA Falcon engines (found in many NVIDIA GPUs, e.g., GTX 1080 or RTX 2080)
+
+Note that using Intel DSA devices requires setting the module parameter
+``vfio_pci.disable_denylist=Y`` to allow ``vfio-pci`` to bind to DSA devices.
+
+Setting up Devices
+------------------
+
+.. code-block:: sh
+
+    tools/testing/selftests/vfio/scripts/setup.sh 0000:01:00.0
+
+The script handles unbinding the device from its current driver and binding it
+to ``vfio-pci``. Metadata about this device is stored in
+``/tmp/vfio-selftests-devices`` so that the device can be cleaned up later
+(bound back to its original driver).
+
+Execution
+---------
+
+VFIO selftests expect the PCI device BDF string as their final command-line
+argument. e.g.
+
+.. code-block:: sh
+
+    tools/testing/selftests/vfio/vfio_pci_device_test 0000:01:00.0
+
+Alternatively, the PCI device BDF can be passed via the ``VFIO_SELFTESTS_BDF``
+environment variable, which can be useful when running all tests:
+
+.. code-block:: sh
+
+	export VFIO_SELFTESTS_BDF=0000:01:00.0
+	make -C tools/testing/selftests TARGETS=vfio install
+	tools/testing/selftests/kselftest_install/run_kselftest.sh -c vfio
+
+Cleanup
+-------
+
+.. code-block:: sh
+
+    tools/testing/selftests/vfio/scripts/cleanup.sh
+
+This script handles unbinding all previously setup devices from ``vfio-pci``
+and binding them back to their original driver. Specific devices can be cleaned
+up by passing their BDF string to the cleanup script.
+
+Writing Tests
+=============
+
+VFIO selftests leverage the ``kselftest_harness.h`` macros to structure setup
+and teardown scenarios. A basic test involves:
+
+1. Declaring a test FIXTURE containing the device and IOMMU state.
+2. Generating test variants that span the different IOMMU modes utilizing
+   ``FIXTURE_VARIANT_ADD_ALL_IOMMU_MODES()``.
+3. Initializing the device and binding the default driver ops.
+
+For a complete example of writing a VFIO selftest, refer to
+``tools/testing/selftests/vfio/vfio_pci_device_test.c``.
+
+VFIO Selftests Library (libvfio)
+================================
+
+The selftests directory contains a helper library compiled from the ``lib/``
+subdirectory. It provides structures and helper functions to handle standard
+operations like opening VFIO devices, creating VFIO containers, and interacting
+with VFIO and IOMMUFD.
+
+All VFIO selftests have libvfio linked in by default. Tests can access the
+library by including ``<libvfio.h>``.
+
+Core Objects
+------------
+
+The VFIO selftests framework revolves around two distinct core objects:
+``struct iommu`` and ``struct vfio_pci_device``. It is important to understand
+the distinction and relationship between them:
+
+- ``struct iommu`` represents an IOMMU domain and the API used to program it
+  (e.g. legacy VFIO Type1 vs IOMMUFD). It is responsible for managing the I/O
+  address space, handling DMA mappings, and translating between host virtual
+  addresses (HVA) and IO virtual addresses (IOVA).
+
+- ``struct vfio_pci_device`` represents a single PCI device. It encapsulates
+  the VFIO device file descriptor, handles access to the PCI configuration
+  space, manages memory-mapped BARs, and drives device interrupts.
+
+A typical test initializes an IOMMU instance first, then passes it when
+initializing one or more PCI devices, linking the devices to the shared IOMMU
+domain.
+
+``struct iommu``
+^^^^^^^^^^^^^^^^
+
+The ``struct iommu`` abstracts away the complexity of managing VFIO containers,
+IOMMU groups, and IOMMUFD contexts. A test allocates its IOMMU handle using
+``iommu_init()`` passing one of the supported IOMMU modes:
+
+.. code-block:: c
+
+    struct iommu *iommu = iommu_init(MODE_IOMMUFD);
+    ...
+    iommu_cleanup(iommu);
+
+The selftest framework is designed to work uniformly across all standard kernel
+IOMMU APIs. The defined modes (in ``iommu.h``) include:
+
+- ``MODE_VFIO_TYPE1_IOMMU``
+- ``MODE_VFIO_TYPE1V2_IOMMU``
+- ``MODE_IOMMUFD_COMPAT_TYPE1``
+- ``MODE_IOMMUFD_COMPAT_TYPE1V2``
+- ``MODE_IOMMUFD``
+
+VFIO selftests can replicate their test cases across all possible IOMMU modes
+using FIXTURE_VARIANT_ADD_ALL_IOMMU_MODES() to ensure kernel IOMMU APIs remain
+compatible.
+
+``struct vfio_pci_device``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A PCI device is represented as a ``struct vfio_pci_device``. The device
+representation is initialized using ``vfio_pci_device_init()``, which takes a
+target BDF string, opens the device in VFIO, and binds it to an existing
+``struct iommu`` instance:
+
+.. code-block:: c
+
+    struct vfio_pci_device *device = vfio_pci_device_init(device_bdf, iommu);
+    ...
+    vfio_pci_device_cleanup(device);
+
+``struct iova_allocator``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To facilitate DMA mappings without hardcoding IOVAs (IO virtual addresses) that
+might conflict with reserved platform address ranges, the library provides a
+``struct iova_allocator``.
+
+The IOVA allocator queries the underlying IOMMU (via ``struct iommu``) for its
+valid target IOVA ranges. Tests can safely carve out unique contiguous chunks
+of IOVA space for device DMA by repeatedly calling:
+
+.. code-block:: c
+
+    struct iova_allocator *allocator = iova_allocator_init(iommu);
+    iova_t addr = iova_allocator_alloc(allocator, size);
+
+Driver Framework
+----------------
+
+The primary goal of VFIO selftests is to verify the correctness of the kernel
+code handling VFIO devices, including VFIO core, IOMMUFD, IOMMU drivers, page
+pinning, DMA mapping/unmapping, interrupt remapping, and IRQ delivery.
+
+Because different physical devices have vastly different programming interfaces
+for triggering work, the selftests library implements a standard driver
+framework.  This framework abstracts diverse hardware endpoints (such as Intel
+IGB, IOAT, or DSA) behind a uniform interface, allowing tests to provoke a
+broad range of devices to generate DMA operations and interrupts in a
+standardized manner.
+
+By exercising DMA and interrupts with real endpoints, tests can thoroughly
+stress and validate the underlying kernel paths, such as IOMMU page table
+management, dirty page tracking, Device TLB and IOTLB invalidations, and
+interrupt delivery under authentic hardware conditions.
+
+All endpoint driver implementations populate a common set of operations defined
+in ``struct vfio_pci_driver_ops``:
+
+- ``probe()``: Validate whether the driver supports the current PCI device
+  (e.g. matching vendor/device IDs).
+- ``init()``: Set up specific control registers or ring-buffer data structures.
+- ``remove()``: Clean up structures before destruction.
+- ``memcpy_start()``: Initiate DMA copies via the device.
+- ``memcpy_wait()``: Poll and wait until previously initiated copies complete
+  safely.
+- ``send_msi()``: Provoke the device to signal an MSI interrupt.
+
+Tests are required to set up a dedicated DMA region for the driver to use
+within ``struct vfio_pci_driver`` to serve as the driver's main memory
+allocation region (e.g. used for in-memory descriptor rings and hardware
+buffers). Tests must provision and map this DMA region before completing driver
+initialization.
+
+For a complete example of interacting with the driver framework from a test
+perspective, refer to ``tools/testing/selftests/vfio/vfio_pci_driver_test.c``.
+
+When contributing a new driver implementation to the selftests library, the
+primary acceptance criteria is that ``vfio_pci_driver_test`` passes using the
+new driver and target device.
+
+Integration with KVM Selftests
+------------------------------
+
+libvfio is not strictly limited to VFIO selftests, it is also leveraged within
+KVM selftests (``tools/testing/selftests/kvm/``). KVM selftests build their own
+copy of libvfio and link against it, enabling libvfio to be used in KVM
+selftests.
+
+This integration enables testing the interaction between KVM and VFIO and
+IOMMUFD. For example, testing the end-to-end delivery of device interrupts into
+running vCPUs.
+
+Contribution Guidelines
+=======================
+
+- Prefer the shortlog prefix ``vfio: selftests: ...`` for commits that modify
+  files in ``tools/testing/selftests/vfio/``.
+- Follow the Coding Style, Comments, Changelogs, and Function References
+  guidelines from the
+  :doc:`KVM x86 maintainers handbook </process/maintainer-kvm-x86>`.
diff --git a/MAINTAINERS b/MAINTAINERS
index 806bd2d80d153..ba174dd8ba1b8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28396,6 +28396,7 @@ VFIO SELFTESTS
 M:	David Matlack <dmatlack@google.com>
 L:	kvm@vger.kernel.org
 S:	Maintained
+F:	Documentation/driver-api/vfio-selftests.rst
 F:	tools/testing/selftests/vfio/
 
 VFIO VIRTIO PCI DRIVER

gemini-3.7-flash

null

null

							input: 5977
							output: 85
							thoughts: 502
						

**WorthFuzzing Decision for This Patch**

Okay, let's break this down. First, I need to look at the diff. The provided patch touches `Documentation/driver-api/index.rst`, a *new* file `Documentation/driver-api/vfio-selftests.rst`, and the `MAINTAINERS` file. No compiled C code or kernel headers changed.

Now, let's consult the rules. Section 2, the negative criteria for `WorthFuzzing`, is the relevant section here. It explicitly states that we should return `false` if *all* modified code falls into specific categories. Let's see... the rules mention documentation changes, user-space self-tests that don't affect the kernel image, and build system or Kconfig changes. The changes in this commit are solely to documentation files in `Documentation/` and the `MAINTAINERS` file. It's all documentation and metadata! No executable C logic or kernel headers involved. 

I'll double-check that no other files changed. I've already confirmed the files listed in the initial prompt are the only ones changed from the `diff` data. So, the patch is completely non-executable and just documentation/metadata changes.

Therefore, the verdict is clear: `WorthFuzzing: false`. No fuzzing is warranted here. I can also confidently set `FocusSymbols: []` and `EnableConfigs: []` because the changes are purely documentation-related. I will specify my reasoning as: "The patch only adds documentation for VFIO selftests (in Documentation/driver-api/vfio-selftests.rst and Documentation/driver-api/index.rst) and updates the MAINTAINERS file. No kernel executable code is modified."

Finally, I'll go ahead and call the `set-results` tool to put this conclusion into action.

{
  "EnableConfigs": [],
  "FocusSymbols": [],
  "Reasoning": "The patch only adds documentation for VFIO selftests (Documentation/driver-api/vfio-selftests.rst, Documentation/driver-api/index.rst) and updates the MAINTAINERS file. No kernel executable code or headers are modified.",
  "WorthFuzzing": false
}

{
  "EnableConfigs": null,
  "FocusSymbols": [],
  "Reasoning": "The patch only adds documentation for VFIO selftests (Documentation/driver-api/vfio-selftests.rst, Documentation/driver-api/index.rst) and updates the MAINTAINERS file. No kernel executable code or headers are modified.",
  "WorthFuzzing": false
}

{
  "WorthFuzzing": false
}

null