Skip to contentSkip to conversation

vfio-pci: Provide reviewers and acceptance criteria for vendor drivers

PATCH Superseded Alex Williamson 3 participants 5 messages Mar 14, 2022

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 vfio-pci: Provide reviewers and acceptance criteria for vendor drivers

Vendor or device specific extensions for devices exposed to userspace through the vfio-pci-core library open both new functionality and new risks. Here we attempt to provided formalized requirements and expectations to ensure that future drivers both collaborate in their interaction with existing host drivers, as well as receive additional reviews from community members with experience in this area.

Cc Jason Gunthorpe <[email protected]>
Cc Yishai Hadas <[email protected]>
Cc Shameer Kolothum <[email protected]>
Cc Kevin Tian <[email protected]>

---

v2:

Added Yishai

v1:

Per the proposal here[1], I've collected those that volunteered and those that I interpreted as showing interest (alpha by last name). For those on the reviewers list below, please R-b/A-b to keep your name as a reviewer. More volunteers are still welcome, please let me know explicitly; R-b/A-b will not be used to automatically add reviewers but are of course welcome. Thanks,

Alex

[1]https://lore.kernel.org/all/[email protected]/

 .../vfio/vfio-pci-vendor-driver-acceptance.rst     |   35 ++++++++++++++++++++
 MAINTAINERS                                        |   10 ++++++
 2 files changed, 45 insertions(+)
 create mode 100644 Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst
Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst new file +35 -0
new file mode 100644
index 000000000000..3a108d748681
@@ -0,0 +1,35 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Acceptance criteria for vfio-pci device specific driver variants
+================================================================
+
+Overview
+--------
+The vfio-pci driver exists as a device agnostic driver using the
+system IOMMU and relying on the robustness of platform fault
+handling to provide isolated device access to userspace.  While the
+vfio-pci driver does include some device specific support, further
+extensions for yet more advanced device specific features are not
+sustainable.  The vfio-pci driver has therefore split out
+vfio-pci-core as a library that may be reused to implement features
+requiring device specific knowledge, ex. saving and loading device
+state for the purposes of supporting migration.
+
+In support of such features, it's expected that some device specific
+variants may interact with parent devices (ex. SR-IOV PF in support of
+a user assigned VF) or other extensions that may not be otherwise
+accessible via the vfio-pci base driver.  Authors of such drivers
+should be diligent not to create exploitable interfaces via such
+interactions or allow unchecked userspace data to have an effect
+beyond the scope of the assigned device.
+
+New driver submissions are therefore requested to have approval via
+Sign-off/Acked-by/etc for any interactions with parent drivers.
+Additionally, drivers should make an attempt to provide sufficient
+documentation for reviewers to understand the device specific
+extensions, for example in the case of migration data, how is the
+device state composed and consumed, which portions are not otherwise
+available to the user via vfio-pci, what safeguards exist to validate
+the data, etc.  To that extent, authors should additionally expect to
+require reviews from at least one of the listed reviewers, in addition
+to the overall vfio maintainer.
MAINTAINERS +10 -0
index 4322b5321891..7f6b14013412 100644
@@ -20314,6 +20314,16 @@ F:	drivers/vfio/mdev/
 F:	include/linux/mdev.h
 F:	samples/vfio-mdev/
 
+VFIO PCI VENDOR DRIVERS
+R:	Jason Gunthorpe <[email protected]>
+R:	Yishai Hadas <[email protected]>
+R:	Shameer Kolothum <[email protected]>
+R:	Kevin Tian <[email protected]>
+L:	[email protected]
+S:	Maintained
+P:	Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst
+F:	drivers/vfio/pci/*/
+
 VFIO PLATFORM DRIVER
 M:	Eric Auger <[email protected]>
 L:	[email protected]
Acked-by on v2 1/1
#1 lore raw
Quoted 19 lines

-----Original Message-----
From: Alex Williamson [mailto:[email protected]]
Sent: 14 March 2022 19:15
To: [email protected]; [email protected]
Cc: [email protected]; [email protected]; Shameerali Kolothum Thodi <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]
Subject: [PATCH v2] vfio-pci: Provide reviewers and acceptance criteria for vendor drivers

Vendor or device specific extensions for devices exposed to userspace through the vfio-pci-core library open both new functionality and new risks. Here we attempt to provided formalized requirements and expectations to ensure that future drivers both collaborate in their interaction with existing host drivers, as well as receive additional reviews from community members with experience in this area.

Quoted 5 lines
Cc Jason Gunthorpe <[email protected]>
Cc Yishai Hadas <[email protected]>
Cc Shameer Kolothum <[email protected]>
Cc Kevin Tian <[email protected]>

Thanks,
Shameer

Quoted 91 lines

---

v2:

Added Yishai

v1:

Per the proposal here[1], I've collected those that volunteered and those that I interpreted as showing interest (alpha by last name). For those on the reviewers list below, please R-b/A-b to keep your name as a reviewer. More volunteers are still welcome, please let me know explicitly; R-b/A-b will not be used to automatically add reviewers but are of course welcome. Thanks,

Alex

[1]https://lore.kernel.org/all/20220310134954.0df4bb12.alex.williamson@red hat.com/

 .../vfio/vfio-pci-vendor-driver-acceptance.rst     |   35
++++++++++++++++++++
 MAINTAINERS                                        |   10 ++++++
 2 files changed, 45 insertions(+)
 create mode 100644

Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst

Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst new file +35 -0
new file mode 100644
index 000000000000..3a108d748681
@@ -0,0 +1,35 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Acceptance criteria for vfio-pci device specific driver variants
+================================================================
+
+Overview
+--------
+The vfio-pci driver exists as a device agnostic driver using the
+system IOMMU and relying on the robustness of platform fault
+handling to provide isolated device access to userspace.  While the
+vfio-pci driver does include some device specific support, further
+extensions for yet more advanced device specific features are not
+sustainable.  The vfio-pci driver has therefore split out
+vfio-pci-core as a library that may be reused to implement features
+requiring device specific knowledge, ex. saving and loading device
+state for the purposes of supporting migration.
+
+In support of such features, it's expected that some device specific
+variants may interact with parent devices (ex. SR-IOV PF in support of
+a user assigned VF) or other extensions that may not be otherwise
+accessible via the vfio-pci base driver.  Authors of such drivers
+should be diligent not to create exploitable interfaces via such
+interactions or allow unchecked userspace data to have an effect
+beyond the scope of the assigned device.
+
+New driver submissions are therefore requested to have approval via
+Sign-off/Acked-by/etc for any interactions with parent drivers.
+Additionally, drivers should make an attempt to provide sufficient
+documentation for reviewers to understand the device specific
+extensions, for example in the case of migration data, how is the
+device state composed and consumed, which portions are not otherwise
+available to the user via vfio-pci, what safeguards exist to validate
+the data, etc.  To that extent, authors should additionally expect to
+require reviews from at least one of the listed reviewers, in addition
+to the overall vfio maintainer.
MAINTAINERS +10 -0
index 4322b5321891..7f6b14013412 100644
@@ -20314,6 +20314,16 @@ F:	drivers/vfio/mdev/
 F:	include/linux/mdev.h
 F:	samples/vfio-mdev/
 
+VFIO PCI VENDOR DRIVERS
+R:	Jason Gunthorpe <[email protected]>
+R:	Yishai Hadas <[email protected]>
+R:	Shameer Kolothum <[email protected]>
+R:	Kevin Tian <[email protected]>
+L:	[email protected]
+S:	Maintained
+P:	Documentation/vfio/vfio-pci-vendor-driver-acceptance.rst
+F:	drivers/vfio/pci/*/
+
 VFIO PLATFORM DRIVER
 M:	Eric Auger <[email protected]>
 L:	[email protected]
maintainer
#2 lore raw
In reply to Alex Williamson
Quoted 7 lines · Alex Williamson

Vendor or device specific extensions for devices exposed to userspace through the vfio-pci-core library open both new functionality and new risks. Here we attempt to provided formalized requirements and expectations to ensure that future drivers both collaborate in their interaction with existing host drivers, as well as receive additional reviews from community members with experience in this area.

Quoted 6 lines
Cc Jason Gunthorpe <[email protected]>
Cc Yishai Hadas <[email protected]>
Cc Shameer Kolothum <[email protected]>
Cc Kevin Tian <[email protected]>

---

One thing...

Quoted 3 lines
 .../vfio/vfio-pci-vendor-driver-acceptance.rst     |   35 ++++++++++++++++++++
 MAINTAINERS                                        |   10 ++++++
 2 files changed, 45 insertions(+)

If you add a new RST file, you need to add it to an index.rst somewhere so that it becomes part of the kernel docs build.

Also, though: can we avoid creating a new top-level documentation directory for just this file? It seems like it would logically be a part of the maintainers guide (Documentation/maintainer) ... ?

Thanks,

jon

#3 lore raw

Hi Jon,

Quoted 16 lines · On Mon, 14 Mar 2022 13:42:51 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 7 lines · Alex Williamson

Vendor or device specific extensions for devices exposed to userspace through the vfio-pci-core library open both new functionality and new risks. Here we attempt to provided formalized requirements and expectations to ensure that future drivers both collaborate in their interaction with existing host drivers, as well as receive additional reviews from community members with experience in this area.

Quoted 6 lines
Cc Jason Gunthorpe <[email protected]>
Cc Yishai Hadas <[email protected]>
Cc Shameer Kolothum <[email protected]>
Cc Kevin Tian <[email protected]>

---

Quoted 8 lines

One thing...

Quoted 3 lines
 .../vfio/vfio-pci-vendor-driver-acceptance.rst     |   35 ++++++++++++++++++++
 MAINTAINERS                                        |   10 ++++++
 2 files changed, 45 insertions(+)  

If you add a new RST file, you need to add it to an index.rst somewhere so that it becomes part of the kernel docs build.

Whoops

Quoted 3 lines

Also, though: can we avoid creating a new top-level documentation directory for just this file? It seems like it would logically be a part of the maintainers guide (Documentation/maintainer) ... ?

I'm not sure it's appropriate for Documentation/maintainer/ but it would make sense to link it from maintainer-entry-profile.rst there. What if I move it to Documentation/driver-api where there are a couple other vfio docs? Thanks,

Alex

maintainer
#4 lore raw
Quoted 8 lines · Alex Williamson
Quoted 3 lines

Also, though: can we avoid creating a new top-level documentation directory for just this file? It seems like it would logically be a part of the maintainers guide (Documentation/maintainer) ... ?

I'm not sure it's appropriate for Documentation/maintainer/ but it would make sense to link it from maintainer-entry-profile.rst there. What if I move it to Documentation/driver-api where there are a couple other vfio docs? Thanks,

Sure, that's fine.

Thanks,

jon