* Re: [PATCH v4] vfio: Add property documentation
2025-02-17 17:34 [PATCH v4] vfio: Add property documentation Cédric Le Goater
@ 2025-02-17 17:54 ` Eric Auger
2025-02-18 15:19 ` Alex Williamson
` (3 subsequent siblings)
4 siblings, 0 replies; 7+ messages in thread
From: Eric Auger @ 2025-02-17 17:54 UTC (permalink / raw)
To: Cédric Le Goater, qemu-devel
Cc: Alex Williamson, tomitamoeko, corvin.koehne, Kirti Wankhede,
Joao Martins, Tony Krowiak, Eric Farman
On 2/17/25 6:34 PM, Cédric Le Goater wrote:
> Investigate the git history to uncover when and why the VFIO
> properties were introduced and update the models. This is mostly
> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
> devices are simpler.
>
> Sort the properties based on the QEMU version in which they were
> introduced.
>
> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
> Cc: Eric Farman <farman@linux.ibm.com>
> Cc: Eric Auger <eric.auger@redhat.com>
> Signed-off-by: Cédric Le Goater <clg@redhat.com>
> ---
>
> Should we introduce documentation for properties like the kernel has
> in Documentation/ABI/*/sysfs-* ?
>
> Changes in v4:
>
> - Latest improvements from Alex
>
> Changes in v3:
>
> - Re-organized the vfio-pci properties based on the QEMU version in
> which they were introduced
> - Added property labels
> - Improved description as suggested by Alex, Tomita and Corvin
>
> Changes in v2:
>
> - Fixed version numbers
> - Fixed #ifdef in vfio/ccw.c
> - Addressed vfio-pci-nohotplug
> - Organize the vfio-pci properties in topics
>
> hw/vfio/ap.c | 9 ++++
> hw/vfio/ccw.c | 15 ++++++
> hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
> hw/vfio/platform.c | 24 +++++++++
> 4 files changed, 173 insertions(+)
>
> diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
> index 30b08ad375d5ecae886c5000fbaa364799fe76d0..c7ab4ff57ada0ed0e5a76f52b5a05c86ca4fe0b4 100644
> --- a/hw/vfio/ap.c
> +++ b/hw/vfio/ap.c
> @@ -257,6 +257,15 @@ static void vfio_ap_class_init(ObjectClass *klass, void *data)
> dc->hotpluggable = true;
> device_class_set_legacy_reset(dc, vfio_ap_reset);
> dc->bus_type = TYPE_AP_BUS;
> +
> + object_class_property_set_description(klass, /* 3.1 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> }
>
> static const TypeInfo vfio_ap_info = {
> diff --git a/hw/vfio/ccw.c b/hw/vfio/ccw.c
> index 6bb8882d3f2b965eb47cc9e65d7e74bbdb5e7685..e5e0d9e3e7ed124f242b3eda345bc973e418a64c 100644
> --- a/hw/vfio/ccw.c
> +++ b/hw/vfio/ccw.c
> @@ -709,6 +709,21 @@ static void vfio_ccw_class_init(ObjectClass *klass, void *data)
> cdc->handle_halt = vfio_ccw_handle_halt;
> cdc->handle_clear = vfio_ccw_handle_clear;
> cdc->handle_store = vfio_ccw_handle_store;
> +
> + object_class_property_set_description(klass, /* 2.10 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> + object_class_property_set_description(klass, /* 3.0 */
> + "force-orb-pfch",
> + "Force unlimited prefetch");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> + object_class_property_set_description(klass, /* 9.2 */
> + "loadparm",
> + "Define which devices that can be used for booting");
> }
>
> static const TypeInfo vfio_ccw_info = {
> diff --git a/hw/vfio/pci.c b/hw/vfio/pci.c
> index 89d900e9cf0ce364f7c813d81b0317bb3b3e80ca..4f92b50b133060c9199079a0ab620793ecdac0ee 100644
> --- a/hw/vfio/pci.c
> +++ b/hw/vfio/pci.c
> @@ -3433,6 +3433,122 @@ static void vfio_pci_dev_class_init(ObjectClass *klass, void *data)
> pdc->exit = vfio_exitfn;
> pdc->config_read = vfio_pci_read_config;
> pdc->config_write = vfio_pci_write_config;
> +
> + object_class_property_set_description(klass, /* 1.3 */
> + "host",
> + "Host PCI address [domain:]<bus:slot.function> of assigned device");
> + object_class_property_set_description(klass, /* 1.3 */
> + "x-intx-mmap-timeout-ms",
> + "When EOI is not provided by KVM/QEMU, wait time "
> + "(milliseconds) to re-enable device direct access "
> + "after INTx (DEBUG)");
> + object_class_property_set_description(klass, /* 1.5 */
> + "x-vga",
> + "Expose VGA address spaces for device");
> + object_class_property_set_description(klass, /* 2.3 */
> + "x-req",
> + "Disable device request notification support (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
> + "x-no-mmap",
> + "Disable MMAP for device. Allows to trace MMIO "
> + "accesses (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-intx",
> + "Disable direct VFIO->KVM INTx injection. Allows to "
> + "trace INTx interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-msi",
> + "Disable direct VFIO->KVM MSI injection. Allows to "
> + "trace MSI interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-msix",
> + "Disable direct VFIO->KVM MSIx injection. Allows to "
> + "trace MSIx interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-vendor-id",
> + "Override PCI Vendor ID with provided value (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-device-id",
> + "Override PCI device ID with provided value (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-sub-vendor-id",
> + "Override PCI Subsystem Vendor ID with provided value "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-sub-device-id",
> + "Override PCI Subsystem Device ID with provided value "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 2.6 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> + object_class_property_set_description(klass, /* 2.7 */
> + "x-igd-opregion",
> + "Expose host IGD OpRegion to guest");
> + object_class_property_set_description(klass, /* 2.7 (See c4c45e943e51) */
> + "x-igd-gms",
> + "Override IGD data stolen memory size (32MiB units)");
> + object_class_property_set_description(klass, /* 2.11 */
> + "x-nv-gpudirect-clique",
> + "Add NVIDIA GPUDirect capability indicating P2P DMA "
> + "clique for device [0-15]");
> + object_class_property_set_description(klass, /* 2.12 */
> + "x-no-geforce-quirks",
> + "Disable GeForce quirks (for NVIDIA Quadro/GRID/Tesla). "
> + "Improves performance");
> + object_class_property_set_description(klass, /* 2.12 */
> + "display",
> + "Enable display support for device, ex. vGPU");
> + object_class_property_set_description(klass, /* 2.12 */
> + "x-msix-relocation",
> + "Specify MSI-X MMIO relocation to the end of specified "
> + "existing BAR or new BAR to avoid virtualization overhead "
> + "due to adjacent device registers");
> + object_class_property_set_description(klass, /* 3.0 */
> + "x-no-kvm-ioeventfd",
> + "Disable registration of ioeventfds with KVM (DEBUG)");
> + object_class_property_set_description(klass, /* 3.0 */
> + "x-no-vfio-ioeventfd",
> + "Disable linking of KVM ioeventfds to VFIO ioeventfds "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 3.1 */
> + "x-balloon-allowed",
> + "Override allowing ballooning with device (DEBUG, DANGER)");
> + object_class_property_set_description(klass, /* 3.2 */
> + "xres",
> + "Set X display resolution the vGPU should use");
> + object_class_property_set_description(klass, /* 3.2 */
> + "yres",
> + "Set Y display resolution the vGPU should use");
> + object_class_property_set_description(klass, /* 5.2 */
> + "x-pre-copy-dirty-page-tracking",
> + "Disable dirty pages tracking during iterative phase "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 5.2, 8.0 non-experimetal */
> + "enable-migration",
> + "Enale device migration. Also requires a host VFIO PCI "
> + "variant or mdev driver with migration support enabled");
> + object_class_property_set_description(klass, /* 8.1 */
> + "vf-token",
> + "Specify UUID VF token. Required for VF when PF is owned "
> + "by another VFIO driver");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> + object_class_property_set_description(klass, /* 9.1 */
> + "x-device-dirty-page-tracking",
> + "Disable device dirty page tracking and use "
> + "container-based dirty page tracking (DEBUG)");
> + object_class_property_set_description(klass, /* 9.1 */
> + "migration-events",
> + "Emit VFIO migration QAPI event when a VFIO device "
> + "changes its migration state. For management applications");
> + object_class_property_set_description(klass, /* 9.1 */
> + "skip-vsc-check",
> + "Skip config space check for Vendor Specific Capability. "
> + "Setting to false will enforce strict checking of VSC content "
> + "(DEBUG)");
> }
>
> static const TypeInfo vfio_pci_dev_info = {
> @@ -3461,6 +3577,15 @@ static void vfio_pci_nohotplug_dev_class_init(ObjectClass *klass, void *data)
>
> device_class_set_props(dc, vfio_pci_dev_nohotplug_properties);
> dc->hotpluggable = false;
> +
> + object_class_property_set_description(klass, /* 3.1 */
> + "ramfb",
> + "Enable ramfb to provide pre-boot graphics for devices "
> + "enabling display option");
> + object_class_property_set_description(klass, /* 8.2 */
> + "x-ramfb-migrate",
> + "Override default migration support for ramfb support "
> + "(DEBUG)");
> }
>
> static const TypeInfo vfio_pci_nohotplug_dev_info = {
> diff --git a/hw/vfio/platform.c b/hw/vfio/platform.c
> index f491f4dc9543c2ea3a7af4e51ee82fbc7ee6e4bb..d9faaa73959ad36aa3a835b87964ab940928bd9f 100644
> --- a/hw/vfio/platform.c
> +++ b/hw/vfio/platform.c
> @@ -672,6 +672,30 @@ static void vfio_platform_class_init(ObjectClass *klass, void *data)
> dc->desc = "VFIO-based platform device assignment";
> sbc->connect_irq_notifier = vfio_start_irqfd_injection;
> set_bit(DEVICE_CATEGORY_MISC, dc->categories);
> +
> + object_class_property_set_description(klass, /* 2.4 */
> + "host",
> + "Host device name of assigned device");
> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
> + "x-no-mmap",
> + "Disable MMAP for device. Allows to trace MMIO "
> + "accesses (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 */
> + "mmap-timeout-ms",
> + "When EOI is not provided by KVM/QEMU, wait time "
> + "(milliseconds) to re-enable device direct access "
> + "after level interrupt (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 */
> + "x-irqfd",
> + "Allow disabling irqfd support (DEBUG)");
> + object_class_property_set_description(klass, /* 2.6 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
for the vfio-platform part,
Reviewed-by: Eric Auger <eric.auger@redhat.com>
Eric
> }
>
> static const TypeInfo vfio_platform_dev_info = {
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [PATCH v4] vfio: Add property documentation
2025-02-17 17:34 [PATCH v4] vfio: Add property documentation Cédric Le Goater
2025-02-17 17:54 ` Eric Auger
@ 2025-02-18 15:19 ` Alex Williamson
2025-02-18 15:33 ` Cédric Le Goater
2025-02-24 17:07 ` Eric Farman
` (2 subsequent siblings)
4 siblings, 1 reply; 7+ messages in thread
From: Alex Williamson @ 2025-02-18 15:19 UTC (permalink / raw)
To: Cédric Le Goater
Cc: qemu-devel, tomitamoeko, corvin.koehne, Kirti Wankhede,
Joao Martins, Tony Krowiak, Eric Farman, Eric Auger
On Mon, 17 Feb 2025 18:34:55 +0100
Cédric Le Goater <clg@redhat.com> wrote:
> Investigate the git history to uncover when and why the VFIO
> properties were introduced and update the models. This is mostly
> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
> devices are simpler.
>
> Sort the properties based on the QEMU version in which they were
> introduced.
>
> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
> Cc: Eric Farman <farman@linux.ibm.com>
> Cc: Eric Auger <eric.auger@redhat.com>
> Signed-off-by: Cédric Le Goater <clg@redhat.com>
> ---
>
> Should we introduce documentation for properties like the kernel has
> in Documentation/ABI/*/sysfs-* ?
>
> Changes in v4:
>
> - Latest improvements from Alex
>
> Changes in v3:
>
> - Re-organized the vfio-pci properties based on the QEMU version in
> which they were introduced
> - Added property labels
> - Improved description as suggested by Alex, Tomita and Corvin
>
> Changes in v2:
>
> - Fixed version numbers
> - Fixed #ifdef in vfio/ccw.c
> - Addressed vfio-pci-nohotplug
> - Organize the vfio-pci properties in topics
>
> hw/vfio/ap.c | 9 ++++
> hw/vfio/ccw.c | 15 ++++++
> hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
> hw/vfio/platform.c | 24 +++++++++
> 4 files changed, 173 insertions(+)
>
> diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
> index 30b08ad375d5ecae886c5000fbaa364799fe76d0..c7ab4ff57ada0ed0e5a76f52b5a05c86ca4fe0b4 100644
> --- a/hw/vfio/ap.c
> +++ b/hw/vfio/ap.c
> @@ -257,6 +257,15 @@ static void vfio_ap_class_init(ObjectClass *klass, void *data)
> dc->hotpluggable = true;
> device_class_set_legacy_reset(dc, vfio_ap_reset);
> dc->bus_type = TYPE_AP_BUS;
> +
> + object_class_property_set_description(klass, /* 3.1 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> }
>
> static const TypeInfo vfio_ap_info = {
> diff --git a/hw/vfio/ccw.c b/hw/vfio/ccw.c
> index 6bb8882d3f2b965eb47cc9e65d7e74bbdb5e7685..e5e0d9e3e7ed124f242b3eda345bc973e418a64c 100644
> --- a/hw/vfio/ccw.c
> +++ b/hw/vfio/ccw.c
> @@ -709,6 +709,21 @@ static void vfio_ccw_class_init(ObjectClass *klass, void *data)
> cdc->handle_halt = vfio_ccw_handle_halt;
> cdc->handle_clear = vfio_ccw_handle_clear;
> cdc->handle_store = vfio_ccw_handle_store;
> +
> + object_class_property_set_description(klass, /* 2.10 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> + object_class_property_set_description(klass, /* 3.0 */
> + "force-orb-pfch",
> + "Force unlimited prefetch");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> + object_class_property_set_description(klass, /* 9.2 */
> + "loadparm",
> + "Define which devices that can be used for booting");
> }
>
> static const TypeInfo vfio_ccw_info = {
> diff --git a/hw/vfio/pci.c b/hw/vfio/pci.c
> index 89d900e9cf0ce364f7c813d81b0317bb3b3e80ca..4f92b50b133060c9199079a0ab620793ecdac0ee 100644
> --- a/hw/vfio/pci.c
> +++ b/hw/vfio/pci.c
> @@ -3433,6 +3433,122 @@ static void vfio_pci_dev_class_init(ObjectClass *klass, void *data)
> pdc->exit = vfio_exitfn;
> pdc->config_read = vfio_pci_read_config;
> pdc->config_write = vfio_pci_write_config;
> +
> + object_class_property_set_description(klass, /* 1.3 */
> + "host",
> + "Host PCI address [domain:]<bus:slot.function> of assigned device");
> + object_class_property_set_description(klass, /* 1.3 */
> + "x-intx-mmap-timeout-ms",
> + "When EOI is not provided by KVM/QEMU, wait time "
> + "(milliseconds) to re-enable device direct access "
> + "after INTx (DEBUG)");
> + object_class_property_set_description(klass, /* 1.5 */
> + "x-vga",
> + "Expose VGA address spaces for device");
> + object_class_property_set_description(klass, /* 2.3 */
> + "x-req",
> + "Disable device request notification support (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
> + "x-no-mmap",
> + "Disable MMAP for device. Allows to trace MMIO "
> + "accesses (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-intx",
> + "Disable direct VFIO->KVM INTx injection. Allows to "
> + "trace INTx interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-msi",
> + "Disable direct VFIO->KVM MSI injection. Allows to "
> + "trace MSI interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-no-kvm-msix",
> + "Disable direct VFIO->KVM MSIx injection. Allows to "
> + "trace MSIx interrupts (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-vendor-id",
> + "Override PCI Vendor ID with provided value (DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-device-id",
> + "Override PCI device ID with provided value (DEBUG)");
nit for consistency, s/device/Device/ Otherwise:
Reviewed-by: Alex Williamson <alex.williamson@redhat.com>
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-sub-vendor-id",
> + "Override PCI Subsystem Vendor ID with provided value "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 2.5 */
> + "x-pci-sub-device-id",
> + "Override PCI Subsystem Device ID with provided value "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 2.6 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> + object_class_property_set_description(klass, /* 2.7 */
> + "x-igd-opregion",
> + "Expose host IGD OpRegion to guest");
> + object_class_property_set_description(klass, /* 2.7 (See c4c45e943e51) */
> + "x-igd-gms",
> + "Override IGD data stolen memory size (32MiB units)");
> + object_class_property_set_description(klass, /* 2.11 */
> + "x-nv-gpudirect-clique",
> + "Add NVIDIA GPUDirect capability indicating P2P DMA "
> + "clique for device [0-15]");
> + object_class_property_set_description(klass, /* 2.12 */
> + "x-no-geforce-quirks",
> + "Disable GeForce quirks (for NVIDIA Quadro/GRID/Tesla). "
> + "Improves performance");
> + object_class_property_set_description(klass, /* 2.12 */
> + "display",
> + "Enable display support for device, ex. vGPU");
> + object_class_property_set_description(klass, /* 2.12 */
> + "x-msix-relocation",
> + "Specify MSI-X MMIO relocation to the end of specified "
> + "existing BAR or new BAR to avoid virtualization overhead "
> + "due to adjacent device registers");
> + object_class_property_set_description(klass, /* 3.0 */
> + "x-no-kvm-ioeventfd",
> + "Disable registration of ioeventfds with KVM (DEBUG)");
> + object_class_property_set_description(klass, /* 3.0 */
> + "x-no-vfio-ioeventfd",
> + "Disable linking of KVM ioeventfds to VFIO ioeventfds "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 3.1 */
> + "x-balloon-allowed",
> + "Override allowing ballooning with device (DEBUG, DANGER)");
> + object_class_property_set_description(klass, /* 3.2 */
> + "xres",
> + "Set X display resolution the vGPU should use");
> + object_class_property_set_description(klass, /* 3.2 */
> + "yres",
> + "Set Y display resolution the vGPU should use");
> + object_class_property_set_description(klass, /* 5.2 */
> + "x-pre-copy-dirty-page-tracking",
> + "Disable dirty pages tracking during iterative phase "
> + "(DEBUG)");
> + object_class_property_set_description(klass, /* 5.2, 8.0 non-experimetal */
> + "enable-migration",
> + "Enale device migration. Also requires a host VFIO PCI "
> + "variant or mdev driver with migration support enabled");
> + object_class_property_set_description(klass, /* 8.1 */
> + "vf-token",
> + "Specify UUID VF token. Required for VF when PF is owned "
> + "by another VFIO driver");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> + object_class_property_set_description(klass, /* 9.1 */
> + "x-device-dirty-page-tracking",
> + "Disable device dirty page tracking and use "
> + "container-based dirty page tracking (DEBUG)");
> + object_class_property_set_description(klass, /* 9.1 */
> + "migration-events",
> + "Emit VFIO migration QAPI event when a VFIO device "
> + "changes its migration state. For management applications");
> + object_class_property_set_description(klass, /* 9.1 */
> + "skip-vsc-check",
> + "Skip config space check for Vendor Specific Capability. "
> + "Setting to false will enforce strict checking of VSC content "
> + "(DEBUG)");
> }
>
> static const TypeInfo vfio_pci_dev_info = {
> @@ -3461,6 +3577,15 @@ static void vfio_pci_nohotplug_dev_class_init(ObjectClass *klass, void *data)
>
> device_class_set_props(dc, vfio_pci_dev_nohotplug_properties);
> dc->hotpluggable = false;
> +
> + object_class_property_set_description(klass, /* 3.1 */
> + "ramfb",
> + "Enable ramfb to provide pre-boot graphics for devices "
> + "enabling display option");
> + object_class_property_set_description(klass, /* 8.2 */
> + "x-ramfb-migrate",
> + "Override default migration support for ramfb support "
> + "(DEBUG)");
> }
>
> static const TypeInfo vfio_pci_nohotplug_dev_info = {
> diff --git a/hw/vfio/platform.c b/hw/vfio/platform.c
> index f491f4dc9543c2ea3a7af4e51ee82fbc7ee6e4bb..d9faaa73959ad36aa3a835b87964ab940928bd9f 100644
> --- a/hw/vfio/platform.c
> +++ b/hw/vfio/platform.c
> @@ -672,6 +672,30 @@ static void vfio_platform_class_init(ObjectClass *klass, void *data)
> dc->desc = "VFIO-based platform device assignment";
> sbc->connect_irq_notifier = vfio_start_irqfd_injection;
> set_bit(DEVICE_CATEGORY_MISC, dc->categories);
> +
> + object_class_property_set_description(klass, /* 2.4 */
> + "host",
> + "Host device name of assigned device");
> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
> + "x-no-mmap",
> + "Disable MMAP for device. Allows to trace MMIO "
> + "accesses (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 */
> + "mmap-timeout-ms",
> + "When EOI is not provided by KVM/QEMU, wait time "
> + "(milliseconds) to re-enable device direct access "
> + "after level interrupt (DEBUG)");
> + object_class_property_set_description(klass, /* 2.4 */
> + "x-irqfd",
> + "Allow disabling irqfd support (DEBUG)");
> + object_class_property_set_description(klass, /* 2.6 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> }
>
> static const TypeInfo vfio_platform_dev_info = {
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [PATCH v4] vfio: Add property documentation
2025-02-18 15:19 ` Alex Williamson
@ 2025-02-18 15:33 ` Cédric Le Goater
0 siblings, 0 replies; 7+ messages in thread
From: Cédric Le Goater @ 2025-02-18 15:33 UTC (permalink / raw)
To: Alex Williamson
Cc: qemu-devel, tomitamoeko, corvin.koehne, Kirti Wankhede,
Joao Martins, Tony Krowiak, Eric Farman, Eric Auger
On 2/18/25 16:19, Alex Williamson wrote:
> On Mon, 17 Feb 2025 18:34:55 +0100
> Cédric Le Goater <clg@redhat.com> wrote:
>
>> Investigate the git history to uncover when and why the VFIO
>> properties were introduced and update the models. This is mostly
>> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
>> devices are simpler.
>>
>> Sort the properties based on the QEMU version in which they were
>> introduced.
>>
>> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
>> Cc: Eric Farman <farman@linux.ibm.com>
>> Cc: Eric Auger <eric.auger@redhat.com>
>> Signed-off-by: Cédric Le Goater <clg@redhat.com>
>> ---
>>
>> Should we introduce documentation for properties like the kernel has
>> in Documentation/ABI/*/sysfs-* ?
>>
>> Changes in v4:
>>
>> - Latest improvements from Alex
>>
>> Changes in v3:
>>
>> - Re-organized the vfio-pci properties based on the QEMU version in
>> which they were introduced
>> - Added property labels
>> - Improved description as suggested by Alex, Tomita and Corvin
>>
>> Changes in v2:
>>
>> - Fixed version numbers
>> - Fixed #ifdef in vfio/ccw.c
>> - Addressed vfio-pci-nohotplug
>> - Organize the vfio-pci properties in topics
>>
>> hw/vfio/ap.c | 9 ++++
>> hw/vfio/ccw.c | 15 ++++++
>> hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
>> hw/vfio/platform.c | 24 +++++++++
>> 4 files changed, 173 insertions(+)
>>
>> diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
>> index 30b08ad375d5ecae886c5000fbaa364799fe76d0..c7ab4ff57ada0ed0e5a76f52b5a05c86ca4fe0b4 100644
>> --- a/hw/vfio/ap.c
>> +++ b/hw/vfio/ap.c
>> @@ -257,6 +257,15 @@ static void vfio_ap_class_init(ObjectClass *klass, void *data)
>> dc->hotpluggable = true;
>> device_class_set_legacy_reset(dc, vfio_ap_reset);
>> dc->bus_type = TYPE_AP_BUS;
>> +
>> + object_class_property_set_description(klass, /* 3.1 */
>> + "sysfsdev",
>> + "Host sysfs path of assigned device");
>> +#ifdef CONFIG_IOMMUFD
>> + object_class_property_set_description(klass, /* 9.0 */
>> + "iommufd",
>> + "Set host IOMMUFD backend device");
>> +#endif
>> }
>>
>> static const TypeInfo vfio_ap_info = {
>> diff --git a/hw/vfio/ccw.c b/hw/vfio/ccw.c
>> index 6bb8882d3f2b965eb47cc9e65d7e74bbdb5e7685..e5e0d9e3e7ed124f242b3eda345bc973e418a64c 100644
>> --- a/hw/vfio/ccw.c
>> +++ b/hw/vfio/ccw.c
>> @@ -709,6 +709,21 @@ static void vfio_ccw_class_init(ObjectClass *klass, void *data)
>> cdc->handle_halt = vfio_ccw_handle_halt;
>> cdc->handle_clear = vfio_ccw_handle_clear;
>> cdc->handle_store = vfio_ccw_handle_store;
>> +
>> + object_class_property_set_description(klass, /* 2.10 */
>> + "sysfsdev",
>> + "Host sysfs path of assigned device");
>> + object_class_property_set_description(klass, /* 3.0 */
>> + "force-orb-pfch",
>> + "Force unlimited prefetch");
>> +#ifdef CONFIG_IOMMUFD
>> + object_class_property_set_description(klass, /* 9.0 */
>> + "iommufd",
>> + "Set host IOMMUFD backend device");
>> +#endif
>> + object_class_property_set_description(klass, /* 9.2 */
>> + "loadparm",
>> + "Define which devices that can be used for booting");
>> }
>>
>> static const TypeInfo vfio_ccw_info = {
>> diff --git a/hw/vfio/pci.c b/hw/vfio/pci.c
>> index 89d900e9cf0ce364f7c813d81b0317bb3b3e80ca..4f92b50b133060c9199079a0ab620793ecdac0ee 100644
>> --- a/hw/vfio/pci.c
>> +++ b/hw/vfio/pci.c
>> @@ -3433,6 +3433,122 @@ static void vfio_pci_dev_class_init(ObjectClass *klass, void *data)
>> pdc->exit = vfio_exitfn;
>> pdc->config_read = vfio_pci_read_config;
>> pdc->config_write = vfio_pci_write_config;
>> +
>> + object_class_property_set_description(klass, /* 1.3 */
>> + "host",
>> + "Host PCI address [domain:]<bus:slot.function> of assigned device");
>> + object_class_property_set_description(klass, /* 1.3 */
>> + "x-intx-mmap-timeout-ms",
>> + "When EOI is not provided by KVM/QEMU, wait time "
>> + "(milliseconds) to re-enable device direct access "
>> + "after INTx (DEBUG)");
>> + object_class_property_set_description(klass, /* 1.5 */
>> + "x-vga",
>> + "Expose VGA address spaces for device");
>> + object_class_property_set_description(klass, /* 2.3 */
>> + "x-req",
>> + "Disable device request notification support (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
>> + "x-no-mmap",
>> + "Disable MMAP for device. Allows to trace MMIO "
>> + "accesses (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-no-kvm-intx",
>> + "Disable direct VFIO->KVM INTx injection. Allows to "
>> + "trace INTx interrupts (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-no-kvm-msi",
>> + "Disable direct VFIO->KVM MSI injection. Allows to "
>> + "trace MSI interrupts (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-no-kvm-msix",
>> + "Disable direct VFIO->KVM MSIx injection. Allows to "
>> + "trace MSIx interrupts (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-pci-vendor-id",
>> + "Override PCI Vendor ID with provided value (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-pci-device-id",
>> + "Override PCI device ID with provided value (DEBUG)");
>
> nit for consistency, s/device/Device/ Otherwise:
Fixed
> Reviewed-by: Alex Williamson <alex.williamson@redhat.com>
Applied to vfio-next.
Thanks,
C.
>
>
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-pci-sub-vendor-id",
>> + "Override PCI Subsystem Vendor ID with provided value "
>> + "(DEBUG)");
>> + object_class_property_set_description(klass, /* 2.5 */
>> + "x-pci-sub-device-id",
>> + "Override PCI Subsystem Device ID with provided value "
>> + "(DEBUG)");
>> + object_class_property_set_description(klass, /* 2.6 */
>> + "sysfsdev",
>> + "Host sysfs path of assigned device");
>> + object_class_property_set_description(klass, /* 2.7 */
>> + "x-igd-opregion",
>> + "Expose host IGD OpRegion to guest");
>> + object_class_property_set_description(klass, /* 2.7 (See c4c45e943e51) */
>> + "x-igd-gms",
>> + "Override IGD data stolen memory size (32MiB units)");
>> + object_class_property_set_description(klass, /* 2.11 */
>> + "x-nv-gpudirect-clique",
>> + "Add NVIDIA GPUDirect capability indicating P2P DMA "
>> + "clique for device [0-15]");
>> + object_class_property_set_description(klass, /* 2.12 */
>> + "x-no-geforce-quirks",
>> + "Disable GeForce quirks (for NVIDIA Quadro/GRID/Tesla). "
>> + "Improves performance");
>> + object_class_property_set_description(klass, /* 2.12 */
>> + "display",
>> + "Enable display support for device, ex. vGPU");
>> + object_class_property_set_description(klass, /* 2.12 */
>> + "x-msix-relocation",
>> + "Specify MSI-X MMIO relocation to the end of specified "
>> + "existing BAR or new BAR to avoid virtualization overhead "
>> + "due to adjacent device registers");
>> + object_class_property_set_description(klass, /* 3.0 */
>> + "x-no-kvm-ioeventfd",
>> + "Disable registration of ioeventfds with KVM (DEBUG)");
>> + object_class_property_set_description(klass, /* 3.0 */
>> + "x-no-vfio-ioeventfd",
>> + "Disable linking of KVM ioeventfds to VFIO ioeventfds "
>> + "(DEBUG)");
>> + object_class_property_set_description(klass, /* 3.1 */
>> + "x-balloon-allowed",
>> + "Override allowing ballooning with device (DEBUG, DANGER)");
>> + object_class_property_set_description(klass, /* 3.2 */
>> + "xres",
>> + "Set X display resolution the vGPU should use");
>> + object_class_property_set_description(klass, /* 3.2 */
>> + "yres",
>> + "Set Y display resolution the vGPU should use");
>> + object_class_property_set_description(klass, /* 5.2 */
>> + "x-pre-copy-dirty-page-tracking",
>> + "Disable dirty pages tracking during iterative phase "
>> + "(DEBUG)");
>> + object_class_property_set_description(klass, /* 5.2, 8.0 non-experimetal */
>> + "enable-migration",
>> + "Enale device migration. Also requires a host VFIO PCI "
>> + "variant or mdev driver with migration support enabled");
>> + object_class_property_set_description(klass, /* 8.1 */
>> + "vf-token",
>> + "Specify UUID VF token. Required for VF when PF is owned "
>> + "by another VFIO driver");
>> +#ifdef CONFIG_IOMMUFD
>> + object_class_property_set_description(klass, /* 9.0 */
>> + "iommufd",
>> + "Set host IOMMUFD backend device");
>> +#endif
>> + object_class_property_set_description(klass, /* 9.1 */
>> + "x-device-dirty-page-tracking",
>> + "Disable device dirty page tracking and use "
>> + "container-based dirty page tracking (DEBUG)");
>> + object_class_property_set_description(klass, /* 9.1 */
>> + "migration-events",
>> + "Emit VFIO migration QAPI event when a VFIO device "
>> + "changes its migration state. For management applications");
>> + object_class_property_set_description(klass, /* 9.1 */
>> + "skip-vsc-check",
>> + "Skip config space check for Vendor Specific Capability. "
>> + "Setting to false will enforce strict checking of VSC content "
>> + "(DEBUG)");
>> }
>>
>> static const TypeInfo vfio_pci_dev_info = {
>> @@ -3461,6 +3577,15 @@ static void vfio_pci_nohotplug_dev_class_init(ObjectClass *klass, void *data)
>>
>> device_class_set_props(dc, vfio_pci_dev_nohotplug_properties);
>> dc->hotpluggable = false;
>> +
>> + object_class_property_set_description(klass, /* 3.1 */
>> + "ramfb",
>> + "Enable ramfb to provide pre-boot graphics for devices "
>> + "enabling display option");
>> + object_class_property_set_description(klass, /* 8.2 */
>> + "x-ramfb-migrate",
>> + "Override default migration support for ramfb support "
>> + "(DEBUG)");
>> }
>>
>> static const TypeInfo vfio_pci_nohotplug_dev_info = {
>> diff --git a/hw/vfio/platform.c b/hw/vfio/platform.c
>> index f491f4dc9543c2ea3a7af4e51ee82fbc7ee6e4bb..d9faaa73959ad36aa3a835b87964ab940928bd9f 100644
>> --- a/hw/vfio/platform.c
>> +++ b/hw/vfio/platform.c
>> @@ -672,6 +672,30 @@ static void vfio_platform_class_init(ObjectClass *klass, void *data)
>> dc->desc = "VFIO-based platform device assignment";
>> sbc->connect_irq_notifier = vfio_start_irqfd_injection;
>> set_bit(DEVICE_CATEGORY_MISC, dc->categories);
>> +
>> + object_class_property_set_description(klass, /* 2.4 */
>> + "host",
>> + "Host device name of assigned device");
>> + object_class_property_set_description(klass, /* 2.4 and 2.5 */
>> + "x-no-mmap",
>> + "Disable MMAP for device. Allows to trace MMIO "
>> + "accesses (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.4 */
>> + "mmap-timeout-ms",
>> + "When EOI is not provided by KVM/QEMU, wait time "
>> + "(milliseconds) to re-enable device direct access "
>> + "after level interrupt (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.4 */
>> + "x-irqfd",
>> + "Allow disabling irqfd support (DEBUG)");
>> + object_class_property_set_description(klass, /* 2.6 */
>> + "sysfsdev",
>> + "Host sysfs path of assigned device");
>> +#ifdef CONFIG_IOMMUFD
>> + object_class_property_set_description(klass, /* 9.0 */
>> + "iommufd",
>> + "Set host IOMMUFD backend device");
>> +#endif
>> }
>>
>> static const TypeInfo vfio_platform_dev_info = {
>
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v4] vfio: Add property documentation
2025-02-17 17:34 [PATCH v4] vfio: Add property documentation Cédric Le Goater
2025-02-17 17:54 ` Eric Auger
2025-02-18 15:19 ` Alex Williamson
@ 2025-02-24 17:07 ` Eric Farman
2025-02-25 10:48 ` Anthony Krowiak
2025-02-25 12:38 ` Kirti Wankhede
4 siblings, 0 replies; 7+ messages in thread
From: Eric Farman @ 2025-02-24 17:07 UTC (permalink / raw)
To: Cédric Le Goater, qemu-devel
Cc: Alex Williamson, tomitamoeko, corvin.koehne, Kirti Wankhede,
Joao Martins, Tony Krowiak, Eric Auger
On Mon, 2025-02-17 at 18:34 +0100, Cédric Le Goater wrote:
> Investigate the git history to uncover when and why the VFIO
> properties were introduced and update the models. This is mostly
> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
> devices are simpler.
>
> Sort the properties based on the QEMU version in which they were
> introduced.
>
> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
> Cc: Eric Farman <farman@linux.ibm.com>
> Cc: Eric Auger <eric.auger@redhat.com>
> Signed-off-by: Cédric Le Goater <clg@redhat.com>
> ---
>
> Should we introduce documentation for properties like the kernel has
> in Documentation/ABI/*/sysfs-* ?
>
> Changes in v4:
>
> - Latest improvements from Alex
>
> Changes in v3:
>
> - Re-organized the vfio-pci properties based on the QEMU version in
> which they were introduced
> - Added property labels
> - Improved description as suggested by Alex, Tomita and Corvin
>
> Changes in v2:
>
> - Fixed version numbers
> - Fixed #ifdef in vfio/ccw.c
> - Addressed vfio-pci-nohotplug
> - Organize the vfio-pci properties in topics
>
> hw/vfio/ap.c | 9 ++++
> hw/vfio/ccw.c | 15 ++++++
> hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
> hw/vfio/platform.c | 24 +++++++++
> 4 files changed, 173 insertions(+)
Reviewed-by: Eric Farman <farman@linux.ibm.com> # vfio-ccw
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v4] vfio: Add property documentation
2025-02-17 17:34 [PATCH v4] vfio: Add property documentation Cédric Le Goater
` (2 preceding siblings ...)
2025-02-24 17:07 ` Eric Farman
@ 2025-02-25 10:48 ` Anthony Krowiak
2025-02-25 12:38 ` Kirti Wankhede
4 siblings, 0 replies; 7+ messages in thread
From: Anthony Krowiak @ 2025-02-25 10:48 UTC (permalink / raw)
To: Cédric Le Goater, qemu-devel
Cc: Alex Williamson, tomitamoeko, corvin.koehne, Kirti Wankhede,
Joao Martins, Eric Farman, Eric Auger
On 2/17/25 12:34 PM, Cédric Le Goater wrote:
> Investigate the git history to uncover when and why the VFIO
> properties were introduced and update the models. This is mostly
> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
> devices are simpler.
>
> Sort the properties based on the QEMU version in which they were
> introduced.
>
> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
> Cc: Eric Farman <farman@linux.ibm.com>
> Cc: Eric Auger <eric.auger@redhat.com>
> Signed-off-by: Cédric Le Goater <clg@redhat.com>
> ---
>
> Should we introduce documentation for properties like the kernel has
> in Documentation/ABI/*/sysfs-* ?
>
> Changes in v4:
>
> - Latest improvements from Alex
>
> Changes in v3:
>
> - Re-organized the vfio-pci properties based on the QEMU version in
> which they were introduced
> - Added property labels
> - Improved description as suggested by Alex, Tomita and Corvin
>
> Changes in v2:
>
> - Fixed version numbers
> - Fixed #ifdef in vfio/ccw.c
> - Addressed vfio-pci-nohotplug
> - Organize the vfio-pci properties in topics
>
> hw/vfio/ap.c | 9 ++++
> hw/vfio/ccw.c | 15 ++++++
> hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
> hw/vfio/platform.c | 24 +++++++++
> 4 files changed, 173 insertions(+)
>
> diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
> index 30b08ad375d5ecae886c5000fbaa364799fe76d0..c7ab4ff57ada0ed0e5a76f52b5a05c86ca4fe0b4 100644
> --- a/hw/vfio/ap.c
> +++ b/hw/vfio/ap.c
> @@ -257,6 +257,15 @@ static void vfio_ap_class_init(ObjectClass *klass, void *data)
> dc->hotpluggable = true;
> device_class_set_legacy_reset(dc, vfio_ap_reset);
> dc->bus_type = TYPE_AP_BUS;
> +
> + object_class_property_set_description(klass, /* 3.1 */
> + "sysfsdev",
> + "Host sysfs path of assigned device");
> +#ifdef CONFIG_IOMMUFD
> + object_class_property_set_description(klass, /* 9.0 */
> + "iommufd",
> + "Set host IOMMUFD backend device");
> +#endif
> }
>
> static const TypeInfo vfio_ap_info = {
For ap.c:
Reviewed-by: Anthony Krowiak <akrowiak@linux.ibm.com>
>
^ permalink raw reply [flat|nested] 7+ messages in thread* RE: [PATCH v4] vfio: Add property documentation
2025-02-17 17:34 [PATCH v4] vfio: Add property documentation Cédric Le Goater
` (3 preceding siblings ...)
2025-02-25 10:48 ` Anthony Krowiak
@ 2025-02-25 12:38 ` Kirti Wankhede
4 siblings, 0 replies; 7+ messages in thread
From: Kirti Wankhede @ 2025-02-25 12:38 UTC (permalink / raw)
To: Cédric Le Goater, qemu-devel@nongnu.org
Cc: Alex Williamson, tomitamoeko@gmail.com, corvin.koehne@gmail.com,
Joao Martins, Tony Krowiak, Eric Farman, Eric Auger
> -----Original Message-----
> From: Cédric Le Goater <clg@redhat.com>
> Sent: 17 February 2025 11:05 PM
> To: qemu-devel@nongnu.org
> Cc: Alex Williamson <alex.williamson@redhat.com>;
> tomitamoeko@gmail.com; corvin.koehne@gmail.com; Kirti Wankhede
> <kwankhede@nvidia.com>; Joao Martins <joao.m.martins@oracle.com>;
> Cédric Le Goater <clg@redhat.com>; Tony Krowiak
> <akrowiak@linux.ibm.com>; Eric Farman <farman@linux.ibm.com>; Eric Auger
> <eric.auger@redhat.com>
> Subject: [PATCH v4] vfio: Add property documentation
>
> Investigate the git history to uncover when and why the VFIO
> properties were introduced and update the models. This is mostly
> targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
> devices are simpler.
>
> Sort the properties based on the QEMU version in which they were
> introduced.
>
> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
> Cc: Eric Farman <farman@linux.ibm.com>
> Cc: Eric Auger <eric.auger@redhat.com>
> Signed-off-by: Cédric Le Goater <clg@redhat.com>
> ---
>
> Should we introduce documentation for properties like the kernel has
> in Documentation/ABI/*/sysfs-* ?
>
> Changes in v4:
>
> - Latest improvements from Alex
>
> Changes in v3:
>
> - Re-organized the vfio-pci properties based on the QEMU version in
> which they were introduced
> - Added property labels
> - Improved description as suggested by Alex, Tomita and Corvin
>
> Changes in v2:
>
> - Fixed version numbers
> - Fixed #ifdef in vfio/ccw.c
> - Addressed vfio-pci-nohotplug
> - Organize the vfio-pci properties in topics
>
> hw/vfio/ap.c | 9 ++++
> hw/vfio/ccw.c | 15 ++++++
> hw/vfio/pci.c | 125
> +++++++++++++++++++++++++++++++++++++++++++++
> hw/vfio/platform.c | 24 +++++++++
> 4 files changed, 173 insertions(+)
>
Reviewed-by: Kirti Wankhede <kwankhede@nvidia.com>
^ permalink raw reply [flat|nested] 7+ messages in thread