[PATCH v2] vfio: Add property documentation
[PATCH v4] vfio: Add property documentation
1
Investigate the git history to uncover when and why the VFIO
1
Investigate the git history to uncover when and why the VFIO
2
properties were introduced and update the models. This is mostly
2
properties were introduced and update the models. This is mostly
3
targeting vfio-pci device, since vfio-plateform, vfio-ap and vfio-ccw
3
targeting vfio-pci device, since vfio-platform, vfio-ap and vfio-ccw
4
devices are simpler.
4
devices are simpler.
5
5
6
Organize the vfio-pci properties in topics. It would be great to have
6
Sort the properties based on the QEMU version in which they were
7
a way to do the same for the output.
7
introduced.
8
8
9
Cc: Tony Krowiak <akrowiak@linux.ibm.com>
9
Cc: Tony Krowiak <akrowiak@linux.ibm.com>
10
Cc: Eric Farman <farman@linux.ibm.com>
10
Cc: Eric Farman <farman@linux.ibm.com>
11
Cc: Eric Auger <eric.auger@redhat.com>
11
Cc: Eric Auger <eric.auger@redhat.com>
12
Signed-off-by: Cédric Le Goater <clg@redhat.com>
12
Signed-off-by: Cédric Le Goater <clg@redhat.com>
13
---
13
---
14
14
15
Should we introduce documentation for properties like the kernel has
16
in Documentation/ABI/*/sysfs-* ?
17
18
Changes in v4:
19
20
- Latest improvements from Alex
21
22
Changes in v3:
23
24
- Re-organized the vfio-pci properties based on the QEMU version in
25
which they were introduced
26
- Added property labels
27
- Improved description as suggested by Alex, Tomita and Corvin
28
15
Changes in v2:
29
Changes in v2:
16
30
17
- Fixed version numbers
31
- Fixed version numbers
18
- Fixed #ifdef in vfio/ccw.c
32
- Fixed #ifdef in vfio/ccw.c
19
- Addressed vfio-pci-nohotplug
33
- Addressed vfio-pci-nohotplug
20
- Organize the vfio-pci properties in topics
34
- Organize the vfio-pci properties in topics
21
35
22
hw/vfio/ap.c | 9 +++
36
hw/vfio/ap.c | 9 ++++
23
hw/vfio/ccw.c | 15 +++++
37
hw/vfio/ccw.c | 15 ++++++
24
hw/vfio/pci.c | 134 +++++++++++++++++++++++++++++++++++++++++++++
38
hw/vfio/pci.c | 125 +++++++++++++++++++++++++++++++++++++++++++++
25
hw/vfio/platform.c | 23 ++++++++
39
hw/vfio/platform.c | 24 +++++++++
26
4 files changed, 181 insertions(+)
40
4 files changed, 173 insertions(+)
27
41
28
diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
42
diff --git a/hw/vfio/ap.c b/hw/vfio/ap.c
29
index XXXXXXX..XXXXXXX 100644
43
index XXXXXXX..XXXXXXX 100644
30
--- a/hw/vfio/ap.c
44
--- a/hw/vfio/ap.c
31
+++ b/hw/vfio/ap.c
45
+++ b/hw/vfio/ap.c
...
...
38
+ "sysfsdev",
52
+ "sysfsdev",
39
+ "Host sysfs path of assigned device");
53
+ "Host sysfs path of assigned device");
40
+#ifdef CONFIG_IOMMUFD
54
+#ifdef CONFIG_IOMMUFD
41
+ object_class_property_set_description(klass, /* 9.0 */
55
+ object_class_property_set_description(klass, /* 9.0 */
42
+ "iommufd",
56
+ "iommufd",
43
+ "Set host IOMMUFD backend device ");
57
+ "Set host IOMMUFD backend device");
44
+#endif
58
+#endif
45
}
59
}
46
60
47
static const TypeInfo vfio_ap_info = {
61
static const TypeInfo vfio_ap_info = {
48
diff --git a/hw/vfio/ccw.c b/hw/vfio/ccw.c
62
diff --git a/hw/vfio/ccw.c b/hw/vfio/ccw.c
49
index XXXXXXX..XXXXXXX 100644
63
index XXXXXXX..XXXXXXX 100644
50
--- a/hw/vfio/ccw.c
64
--- a/hw/vfio/ccw.c
...
...
61
+ "force-orb-pfch",
75
+ "force-orb-pfch",
62
+ "Force unlimited prefetch");
76
+ "Force unlimited prefetch");
63
+#ifdef CONFIG_IOMMUFD
77
+#ifdef CONFIG_IOMMUFD
64
+ object_class_property_set_description(klass, /* 9.0 */
78
+ object_class_property_set_description(klass, /* 9.0 */
65
+ "iommufd",
79
+ "iommufd",
66
+ "Set host IOMMUFD backend device ");
80
+ "Set host IOMMUFD backend device");
67
+#endif
81
+#endif
68
+ object_class_property_set_description(klass, /* 9.2 */
82
+ object_class_property_set_description(klass, /* 9.2 */
69
+ "loadparm",
83
+ "loadparm",
70
+ "Define which devices that can be used for booting");
84
+ "Define which devices that can be used for booting");
71
}
85
}
...
...
81
pdc->config_write = vfio_pci_write_config;
95
pdc->config_write = vfio_pci_write_config;
82
+
96
+
83
+ object_class_property_set_description(klass, /* 1.3 */
97
+ object_class_property_set_description(klass, /* 1.3 */
84
+ "host",
98
+ "host",
85
+ "Host PCI address [domain:]<bus:slot.function> of assigned device");
99
+ "Host PCI address [domain:]<bus:slot.function> of assigned device");
86
+ object_class_property_set_description(klass, /* 2.6 */
100
+ object_class_property_set_description(klass, /* 1.3 */
87
+ "sysfsdev",
101
+ "x-intx-mmap-timeout-ms",
88
+ "Host sysfs path of assigned device");
102
+ "When EOI is not provided by KVM/QEMU, wait time "
89
+ /*
103
+ "(milliseconds) to re-enable device direct access "
90
+ * Display
104
+ "after INTx (DEBUG)");
91
+ */
92
+
93
+ object_class_property_set_description(klass, /* 1.5 */
105
+ object_class_property_set_description(klass, /* 1.5 */
94
+ "x-vga",
106
+ "x-vga",
95
+ "Add support for VGA MMIO and I/O port access");
107
+ "Expose VGA address spaces for device");
108
+ object_class_property_set_description(klass, /* 2.3 */
109
+ "x-req",
110
+ "Disable device request notification support (DEBUG)");
111
+ object_class_property_set_description(klass, /* 2.4 and 2.5 */
112
+ "x-no-mmap",
113
+ "Disable MMAP for device. Allows to trace MMIO "
114
+ "accesses (DEBUG)");
115
+ object_class_property_set_description(klass, /* 2.5 */
116
+ "x-no-kvm-intx",
117
+ "Disable direct VFIO->KVM INTx injection. Allows to "
118
+ "trace INTx interrupts (DEBUG)");
119
+ object_class_property_set_description(klass, /* 2.5 */
120
+ "x-no-kvm-msi",
121
+ "Disable direct VFIO->KVM MSI injection. Allows to "
122
+ "trace MSI interrupts (DEBUG)");
123
+ object_class_property_set_description(klass, /* 2.5 */
124
+ "x-no-kvm-msix",
125
+ "Disable direct VFIO->KVM MSIx injection. Allows to "
126
+ "trace MSIx interrupts (DEBUG)");
127
+ object_class_property_set_description(klass, /* 2.5 */
128
+ "x-pci-vendor-id",
129
+ "Override PCI Vendor ID with provided value (DEBUG)");
130
+ object_class_property_set_description(klass, /* 2.5 */
131
+ "x-pci-device-id",
132
+ "Override PCI device ID with provided value (DEBUG)");
133
+ object_class_property_set_description(klass, /* 2.5 */
134
+ "x-pci-sub-vendor-id",
135
+ "Override PCI Subsystem Vendor ID with provided value "
136
+ "(DEBUG)");
137
+ object_class_property_set_description(klass, /* 2.5 */
138
+ "x-pci-sub-device-id",
139
+ "Override PCI Subsystem Device ID with provided value "
140
+ "(DEBUG)");
141
+ object_class_property_set_description(klass, /* 2.6 */
142
+ "sysfsdev",
143
+ "Host sysfs path of assigned device");
144
+ object_class_property_set_description(klass, /* 2.7 */
145
+ "x-igd-opregion",
146
+ "Expose host IGD OpRegion to guest");
147
+ object_class_property_set_description(klass, /* 2.7 (See c4c45e943e51) */
148
+ "x-igd-gms",
149
+ "Override IGD data stolen memory size (32MiB units)");
150
+ object_class_property_set_description(klass, /* 2.11 */
151
+ "x-nv-gpudirect-clique",
152
+ "Add NVIDIA GPUDirect capability indicating P2P DMA "
153
+ "clique for device [0-15]");
154
+ object_class_property_set_description(klass, /* 2.12 */
155
+ "x-no-geforce-quirks",
156
+ "Disable GeForce quirks (for NVIDIA Quadro/GRID/Tesla). "
157
+ "Improves performance");
96
+ object_class_property_set_description(klass, /* 2.12 */
158
+ object_class_property_set_description(klass, /* 2.12 */
97
+ "display",
159
+ "display",
98
+ "Add display support");
160
+ "Enable display support for device, ex. vGPU");
161
+ object_class_property_set_description(klass, /* 2.12 */
162
+ "x-msix-relocation",
163
+ "Specify MSI-X MMIO relocation to the end of specified "
164
+ "existing BAR or new BAR to avoid virtualization overhead "
165
+ "due to adjacent device registers");
166
+ object_class_property_set_description(klass, /* 3.0 */
167
+ "x-no-kvm-ioeventfd",
168
+ "Disable registration of ioeventfds with KVM (DEBUG)");
169
+ object_class_property_set_description(klass, /* 3.0 */
170
+ "x-no-vfio-ioeventfd",
171
+ "Disable linking of KVM ioeventfds to VFIO ioeventfds "
172
+ "(DEBUG)");
173
+ object_class_property_set_description(klass, /* 3.1 */
174
+ "x-balloon-allowed",
175
+ "Override allowing ballooning with device (DEBUG, DANGER)");
99
+ object_class_property_set_description(klass, /* 3.2 */
176
+ object_class_property_set_description(klass, /* 3.2 */
100
+ "xres",
177
+ "xres",
101
+ "Set X display resolution the vgpu should use");
178
+ "Set X display resolution the vGPU should use");
102
+ object_class_property_set_description(klass, /* 3.2 */
179
+ object_class_property_set_description(klass, /* 3.2 */
103
+ "yres",
180
+ "yres",
104
+ "Set Y display resolution the vgpu should use");
181
+ "Set Y display resolution the vGPU should use");
105
+
106
+ /*
107
+ * IGD
108
+ */
109
+
110
+ object_class_property_set_description(klass, /* 2.7 */
111
+ "x-igd-opregion",
112
+ "Add IGD OpRegion support for (headless system)");
113
+ object_class_property_set_description(klass, /* 2.7 (See c4c45e943e51) */
114
+ "x-igd-gms",
115
+ "Add Intel graphics legacy mode device assignment support. "
116
+ "Assign 00:02.0 from the host to 00:02.0 in the VM");
117
+
118
+ /*
119
+ * NVIDIA
120
+ */
121
+ object_class_property_set_description(klass, /* 2.12 */
122
+ "x-no-geforce-quirks",
123
+ "Disable GeForce quirks (for NVIDIA Quadro/GRID/Tesla). Improves performance");
124
+ object_class_property_set_description(klass, /* 3.0 */
125
+ "x-no-kvm-ioeventfd",
126
+ "Disable ioeventfd quirk (NVIDIA)");
127
+ object_class_property_set_description(klass, /* 3.0 */
128
+ "x-no-vfio-ioeventfd",
129
+ "Enable ioeventfd quirks to be handled by VFIO directly. Improves performance");
130
+ object_class_property_set_description(klass, /* 2.11 */
131
+ "x-nv-gpudirect-clique",
132
+ "Add NVIDIA GPUDirect Cliques support");
133
+
134
+ /*
135
+ * Migration support
136
+ */
137
+ object_class_property_set_description(klass, /* 5.2 */
182
+ object_class_property_set_description(klass, /* 5.2 */
138
+ "x-pre-copy-dirty-page-tracking",
183
+ "x-pre-copy-dirty-page-tracking",
139
+ "Disable dirty pages tracking during iterative phase");
184
+ "Disable dirty pages tracking during iterative phase "
185
+ "(DEBUG)");
186
+ object_class_property_set_description(klass, /* 5.2, 8.0 non-experimetal */
187
+ "enable-migration",
188
+ "Enale device migration. Also requires a host VFIO PCI "
189
+ "variant or mdev driver with migration support enabled");
190
+ object_class_property_set_description(klass, /* 8.1 */
191
+ "vf-token",
192
+ "Specify UUID VF token. Required for VF when PF is owned "
193
+ "by another VFIO driver");
194
+#ifdef CONFIG_IOMMUFD
195
+ object_class_property_set_description(klass, /* 9.0 */
196
+ "iommufd",
197
+ "Set host IOMMUFD backend device");
198
+#endif
140
+ object_class_property_set_description(klass, /* 9.1 */
199
+ object_class_property_set_description(klass, /* 9.1 */
141
+ "x-device-dirty-page-tracking",
200
+ "x-device-dirty-page-tracking",
142
+ "Disable device dirty page tracking and use container-based dirty page tracking");
201
+ "Disable device dirty page tracking and use "
143
+ object_class_property_set_description(klass, /* 5.2, 8.0 non-experimetal */
202
+ "container-based dirty page tracking (DEBUG)");
144
+ "enable-migration",
145
+ "Enale device migration. Also requires a host VFIO PCI variant "
146
+ "driver with migration support enabled");
147
+ object_class_property_set_description(klass, /* 9.1 */
203
+ object_class_property_set_description(klass, /* 9.1 */
148
+ "migration-events",
204
+ "migration-events",
149
+ "Emit VFIO migration QAPI event when a VFIO device changes its migration "
205
+ "Emit VFIO migration QAPI event when a VFIO device "
150
+ "state. For management applications");
206
+ "changes its migration state. For management applications");
151
+ object_class_property_set_description(klass, /* 9.1 */
207
+ object_class_property_set_description(klass, /* 9.1 */
152
+ "skip-vsc-check",
208
+ "skip-vsc-check",
153
+ "Skip config space check for Vendor Specific Capability. Useful for "
209
+ "Skip config space check for Vendor Specific Capability. "
154
+ "NVIDIA vGPU driver migration");
210
+ "Setting to false will enforce strict checking of VSC content "
155
+
211
+ "(DEBUG)");
156
+ /*
212
}
157
+ * debug, tracing
158
+ */
159
+ object_class_property_set_description(klass, /* 2.4 and 2.5 */
160
+ "x-no-mmap",
161
+ "Disable MMAP for device. Allows to trace MMIO accesses");
162
+ object_class_property_set_description(klass, /* 2.5 */
163
+ "x-no-kvm-intx",
164
+ "Bypass INTx interrupts. Allows interrupt tracing");
165
+ object_class_property_set_description(klass, /* 2.5 */
166
+ "x-no-kvm-msi",
167
+ "Bypass MSI interrupts. Allows interrupt tracing");
168
+ object_class_property_set_description(klass, /* 2.5 */
169
+ "x-no-kvm-msix",
170
+ "Bypass MSIx interrupts. Allows interrupt tracing");
171
+ object_class_property_set_description(klass, /* 2.5 */
172
+ "x-pci-vendor-id",
173
+ "Set emulated PCI Vendor ID. Allows testing quirks");
174
+ object_class_property_set_description(klass, /* 2.5 */
175
+ "x-pci-device-id",
176
+ "Set emulated PCI device ID. Allows testing quirks");
177
+
178
+ /*
179
+ * other
180
+ */
181
+ object_class_property_set_description(klass, /* 8.1 */
182
+ "vf-token",
183
+ "Add support for VF token among PF and VFs (Linux 5.7+)");
184
+ object_class_property_set_description(klass, /* 1.3 */
185
+ "x-intx-mmap-timeout-ms",
186
+ "Timeout value in milliseconds to re-enable BAR mapping when under "
187
+ "INTx interrupts. Improves performance");
188
+ object_class_property_set_description(klass, /* 2.3 */
189
+ "x-req",
190
+ "Add device request notification support (Linux 4.0+)");
191
+ object_class_property_set_description(klass, /* 3.1 */
192
+ "x-balloon-allowed",
193
+ "Allow devices to opt-in for ballooning");
194
+ object_class_property_set_description(klass, /* 2.5 */
195
+ "x-pci-sub-vendor-id",
196
+ "Set emulated PCI Sub-vendor ID");
197
+ object_class_property_set_description(klass, /* 2.5 */
198
+ "x-pci-sub-device-id",
199
+ "Set emulated PCI Sub-device ID");
200
+ object_class_property_set_description(klass, /* 2.12 */
201
+ "x-msix-relocation",
202
+ "Allow relocating MSI-X MMIO on systems which page size is larger "
203
+ "than the PCI spec recommendation. Mostly for sPAPR");
204
+#ifdef CONFIG_IOMMUFD
205
+ object_class_property_set_description(klass, /* 9.0 */
206
+ "iommufd",
207
+ "Set host IOMMUFD backend device ");
208
+#endif
209
}
210
213
211
static const TypeInfo vfio_pci_dev_info = {
214
static const TypeInfo vfio_pci_dev_info = {
212
@@ -XXX,XX +XXX,XX @@ static void vfio_pci_nohotplug_dev_class_init(ObjectClass *klass, void *data)
215
@@ -XXX,XX +XXX,XX @@ static void vfio_pci_nohotplug_dev_class_init(ObjectClass *klass, void *data)
213
216
214
device_class_set_props(dc, vfio_pci_dev_nohotplug_properties);
217
device_class_set_props(dc, vfio_pci_dev_nohotplug_properties);
215
dc->hotpluggable = false;
218
dc->hotpluggable = false;
219
+
216
+ object_class_property_set_description(klass, /* 3.1 */
220
+ object_class_property_set_description(klass, /* 3.1 */
217
+ "ramfb",
221
+ "ramfb",
218
+ "Add ramfb support");
222
+ "Enable ramfb to provide pre-boot graphics for devices "
223
+ "enabling display option");
219
+ object_class_property_set_description(klass, /* 8.2 */
224
+ object_class_property_set_description(klass, /* 8.2 */
220
+ "x-ramfb-migrate",
225
+ "x-ramfb-migrate",
221
+ "Add ramfb migration support");
226
+ "Override default migration support for ramfb support "
222
+
227
+ "(DEBUG)");
223
}
228
}
224
229
225
static const TypeInfo vfio_pci_nohotplug_dev_info = {
230
static const TypeInfo vfio_pci_nohotplug_dev_info = {
226
diff --git a/hw/vfio/platform.c b/hw/vfio/platform.c
231
diff --git a/hw/vfio/platform.c b/hw/vfio/platform.c
227
index XXXXXXX..XXXXXXX 100644
232
index XXXXXXX..XXXXXXX 100644
228
--- a/hw/vfio/platform.c
233
--- a/hw/vfio/platform.c
229
+++ b/hw/vfio/platform.c
234
+++ b/hw/vfio/platform.c
230
@@ -XXX,XX +XXX,XX @@ static void vfio_platform_class_init(ObjectClass *klass, void *data)
235
@@ -XXX,XX +XXX,XX @@ static void vfio_platform_class_init(ObjectClass *klass, void *data)
236
dc->desc = "VFIO-based platform device assignment";
237
sbc->connect_irq_notifier = vfio_start_irqfd_injection;
231
set_bit(DEVICE_CATEGORY_MISC, dc->categories);
238
set_bit(DEVICE_CATEGORY_MISC, dc->categories);
232
/* Supported by TYPE_VIRT_MACHINE */
233
dc->user_creatable = true;
234
+
239
+
235
+ object_class_property_set_description(klass, /* 2.4 */
240
+ object_class_property_set_description(klass, /* 2.4 */
236
+ "host",
241
+ "host",
237
+ "Host device name of assigned device");
242
+ "Host device name of assigned device");
238
+ object_class_property_set_description(klass, /* 2.6 */
239
+ "sysfsdev",
240
+ "Host sysfs path of assigned device");
241
+ object_class_property_set_description(klass, /* 2.4 and 2.5 */
243
+ object_class_property_set_description(klass, /* 2.4 and 2.5 */
242
+ "x-no-mmap",
244
+ "x-no-mmap",
243
+ "Disable MMAP for device. Allows to trace MMIO accesses");
245
+ "Disable MMAP for device. Allows to trace MMIO "
246
+ "accesses (DEBUG)");
244
+ object_class_property_set_description(klass, /* 2.4 */
247
+ object_class_property_set_description(klass, /* 2.4 */
245
+ "mmap-timeout-ms",
248
+ "mmap-timeout-ms",
246
+ "Timeout value in milliseconds to re-enable BAR mapping");
249
+ "When EOI is not provided by KVM/QEMU, wait time "
250
+ "(milliseconds) to re-enable device direct access "
251
+ "after level interrupt (DEBUG)");
247
+ object_class_property_set_description(klass, /* 2.4 */
252
+ object_class_property_set_description(klass, /* 2.4 */
248
+ "x-irqfd",
253
+ "x-irqfd",
249
+ "Use irqfd for IRQ handling");
254
+ "Allow disabling irqfd support (DEBUG)");
250
+
255
+ object_class_property_set_description(klass, /* 2.6 */
251
+#ifdef CONFIG_IOMMUFD
256
+ "sysfsdev",
252
+ object_class_property_set_description(klass, /* 9.0 */
257
+ "Host sysfs path of assigned device");
253
+ "iommufd",
258
+#ifdef CONFIG_IOMMUFD
254
+ "Set host IOMMUFD backend device ");
259
+ object_class_property_set_description(klass, /* 9.0 */
255
+#endif
260
+ "iommufd",
256
+
261
+ "Set host IOMMUFD backend device");
257
}
262
+#endif
263
}
258
264
259
static const TypeInfo vfio_platform_dev_info = {
265
static const TypeInfo vfio_platform_dev_info = {
260
--
266
--
261
2.48.1
267
2.48.1
262
268
263
269
diff view generated by jsdifflib

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.