[v5] drm/doc: device hot-unplug for userspace

Commit Message

Pekka Paalanen July 7, 2020, 11:38 a.m. UTC

From: Pekka Paalanen <[e-mail]>

Set up the expectations on how hot-unplugging a DRM device should look like to
userspace.

Written by Daniel Vetter's request and largely based on his comments in IRC and
from https://lists.freedesktop.org/archives/dri-devel/2020-May/265484.html .

A related Wayland protocol change proposal is at
https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/35

Signed-off-by: Pekka Paalanen <[e-mail]>
Reviewed-by: Daniel Vetter <[e-mail]>
Reviewed-by: Alex Deucher <[e-mail]>
Acked-by: Noralf Trønnes <[e-mail]>
Cc: Andrey Grodzovsky <[e-mail]>
Cc: Dave Airlie <[e-mail]>
Cc: Sean Paul <[e-mail]>
Cc: Simon Ser <[e-mail]>
Cc: Ben Skeggs <[e-mail]>
Cc: Karol Herbst <[e-mail]>

---

This is only about laying out plans for the future, not about what
drivers do today. We'd just like to be sure the goals are reasonable and
everyone is aware of the idea.

Thanks,
pq

v5:
- two grammar fixes (Alex)
- added R-b/A-b, dropped extra Cc

v4:
- two typo fixes (Daniel)

v3:
- update ENODEV doc (Daniel)
- clarify existing vs. new mmaps (Andrey)
- split into KMS and render/cross sections (Andrey, Daniel)
- open() returns ENXIO (open(2) man page)
- ioctls may return ENODEV (Andrey, Daniel)
- new wayland-protocols MR

v2:
- mmap reads/writes undefined (Daniel)
- make render ioctl behaviour driver-specific (Daniel)
- restructure the mmap paragraphs (Daniel)
- chardev minor notes (Simon)
- open behaviour (Daniel)
- DRM leasing behaviour (Daniel)
- added links

Disclaimer: I am a userspace developer writing for other userspace developers.
I took some liberties in defining what should happen without knowing what is
actually possible or what existing drivers already implement.
---
 Documentation/gpu/drm-uapi.rst | 114 ++++++++++++++++++++++++++++++++-
 1 file changed, 113 insertions(+), 1 deletion(-)

Comments

Karol Herbst July 7, 2020, 11:49 a.m. UTC | #1

On Tue, Jul 7, 2020 at 1:38 PM Pekka Paalanen <[e-mail]> wrote:
>
> From: Pekka Paalanen <[e-mail]>
>
> Set up the expectations on how hot-unplugging a DRM device should look like to
> userspace.
>
> Written by Daniel Vetter's request and largely based on his comments in IRC and
> from https://lists.freedesktop.org/archives/dri-devel/2020-May/265484.html .
>
> A related Wayland protocol change proposal is at
> https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/35
>
> Signed-off-by: Pekka Paalanen <[e-mail]>
> Reviewed-by: Daniel Vetter <[e-mail]>
> Reviewed-by: Alex Deucher <[e-mail]>
> Acked-by: Noralf Trønnes <[e-mail]>
> Cc: Andrey Grodzovsky <[e-mail]>
> Cc: Dave Airlie <[e-mail]>
> Cc: Sean Paul <[e-mail]>
> Cc: Simon Ser <[e-mail]>
> Cc: Ben Skeggs <[e-mail]>
> Cc: Karol Herbst <[e-mail]>
>
> ---
>
> This is only about laying out plans for the future, not about what
> drivers do today. We'd just like to be sure the goals are reasonable and
> everyone is aware of the idea.
>
> Thanks,
> pq
>
> v5:
> - two grammar fixes (Alex)
> - added R-b/A-b, dropped extra Cc
>
> v4:
> - two typo fixes (Daniel)
>
> v3:
> - update ENODEV doc (Daniel)
> - clarify existing vs. new mmaps (Andrey)
> - split into KMS and render/cross sections (Andrey, Daniel)
> - open() returns ENXIO (open(2) man page)
> - ioctls may return ENODEV (Andrey, Daniel)
> - new wayland-protocols MR
>
> v2:
> - mmap reads/writes undefined (Daniel)
> - make render ioctl behaviour driver-specific (Daniel)
> - restructure the mmap paragraphs (Daniel)
> - chardev minor notes (Simon)
> - open behaviour (Daniel)
> - DRM leasing behaviour (Daniel)
> - added links
>
> Disclaimer: I am a userspace developer writing for other userspace developers.
> I took some liberties in defining what should happen without knowing what is
> actually possible or what existing drivers already implement.
> ---
>  Documentation/gpu/drm-uapi.rst | 114 ++++++++++++++++++++++++++++++++-
>  1 file changed, 113 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 56fec6ed1ad8..9ce51e4f98f4 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -1,3 +1,5 @@
> +.. Copyright 2020 DisplayLink (UK) Ltd.
> +
>  ===================
>  Userland interfaces
>  ===================
> @@ -162,6 +164,116 @@ other hand, a driver requires shared state between clients which is
>  visible to user-space and accessible beyond open-file boundaries, they
>  cannot support render nodes.
>
> +Device Hot-Unplug
> +=================
> +
> +.. note::
> +   The following is the plan. Implementation is not there yet
> +   (2020 May).
> +
> +Graphics devices (display and/or render) may be connected via USB (e.g.
> +display adapters or docking stations) or Thunderbolt (e.g. eGPU). An end
> +user is able to hot-unplug this kind of devices while they are being
> +used, and expects that the very least the machine does not crash. Any
> +damage from hot-unplugging a DRM device needs to be limited as much as
> +possible and userspace must be given the chance to handle it if it wants
> +to. Ideally, unplugging a DRM device still lets a desktop continue to
> +run, but that is going to need explicit support throughout the whole
> +graphics stack: from kernel and userspace drivers, through display
> +servers, via window system protocols, and in applications and libraries.
> +
> +Other scenarios that should lead to the same are: unrecoverable GPU
> +crash, PCI device disappearing off the bus, or forced unbind of a driver
> +from the physical device.
> +
> +In other words, from userspace perspective everything needs to keep on
> +working more or less, until userspace stops using the disappeared DRM
> +device and closes it completely. Userspace will learn of the device
> +disappearance from the device removed uevent, ioctls returning ENODEV
> +(or driver-specific ioctls returning driver-specific things), or open()
> +returning ENXIO.
> +
> +Only after userspace has closed all relevant DRM device and dmabuf file
> +descriptors and removed all mmaps, the DRM driver can tear down its
> +instance for the device that no longer exists. If the same physical
> +device somehow comes back in the mean time, it shall be a new DRM
> +device.
> +

I don't think we can make a general statement like this. Drivers might
have kworker polling on the device or other asynchronous or repeating
jobs it might want to get rid of as soon as possible. I think it
should be fine for the kernel driver to tear down the instance as long
as it doesn't conflict with the goal of system stability. And usually
drivers have some kernel side state for clients anyway, so it could be
handled in this layer instead.

Or maybe I am overlooking something and we really can't do that :/

> +Similar to PIDs, chardev minor numbers are not recycled immediately. A
> +new DRM device always picks the next free minor number compared to the
> +previous one allocated, and wraps around when minor numbers are
> +exhausted.
> +
> +The goal raises at least the following requirements for the kernel and
> +drivers.
> +
> +Requirements for KMS UAPI
> +-------------------------
> +
> +- KMS connectors must change their status to disconnected.
> +
> +- Legacy modesets and pageflips, and atomic commits, both real and
> +  TEST_ONLY, and any other ioctls either fail with ENODEV or fake
> +  success.
> +
> +- Pending non-blocking KMS operations deliver the DRM events userspace
> +  is expecting. This applies also to ioctls that faked success.
> +
> +- open() on a device node whose underlying device has disappeared will
> +  fail with ENXIO.
> +
> +- Attempting to create a DRM lease on a disappeared DRM device will
> +  fail with ENODEV. Existing DRM leases remain and work as listed
> +  above.
> +
> +Requirements for Render and Cross-Device UAPI
> +---------------------------------------------
> +
> +- All GPU jobs that can no longer run must have their fences
> +  force-signalled to avoid inflicting hangs on userspace.
> +  The associated error code is ENODEV.
> +
> +- Some userspace APIs already define what should happen when the device
> +  disappears (OpenGL, GL ES: `GL_KHR_robustness`_; `Vulkan`_:
> +  VK_ERROR_DEVICE_LOST; etc.). DRM drivers are free to implement this
> +  behaviour the way they see best, e.g. returning failures in
> +  driver-specific ioctls and handling those in userspace drivers, or
> +  rely on uevents, and so on.
> +
> +- dmabuf which point to memory that has disappeared will either fail to
> +  import with ENODEV or continue to be successfully imported if it would
> +  have succeeded before the disappearance. See also about memory maps
> +  below for already imported dmabufs.
> +
> +- Attempting to import a dmabuf to a disappeared device will either fail
> +  with ENODEV or succeed if it would have succeeded without the
> +  disappearance.
> +
> +- open() on a device node whose underlying device has disappeared will
> +  fail with ENXIO.
> +
> +.. _GL_KHR_robustness: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_robustness.txt
> +.. _Vulkan: https://www.khronos.org/vulkan/
> +
> +Requirements for Memory Maps
> +----------------------------
> +
> +Memory maps have further requirements that apply to both existing maps
> +and maps created after the device has disappeared. If the underlying
> +memory disappears, the map is created or modified such that reads and
> +writes will still complete successfully but the result is undefined.
> +This applies to both userspace mmap()'d memory and memory pointed to by
> +dmabuf which might be mapped to other devices (cross-device dmabuf
> +imports).
> +
> +Raising SIGBUS is not an option, because userspace cannot realistically
> +handle it. Signal handlers are global, which makes them extremely
> +difficult to use correctly from libraries like those that Mesa produces.
> +Signal handlers are not composable, you can't have different handlers
> +for GPU1 and GPU2 from different vendors, and a third handler for
> +mmapped regular files. Threads cause additional pain with signal
> +handling as well.
> +
>  .. _drm_driver_ioctl:
>
>  IOCTL Support on Device Nodes
> @@ -199,7 +311,7 @@ EPERM/EACCES:
>          difference between EACCES and EPERM.
>
>  ENODEV:
> -        The device is not (yet) present or fully initialized.
> +        The device is not present anymore or is not yet fully initialized.
>
>  EOPNOTSUPP:
>          Feature (like PRIME, modesetting, GEM) is not supported by the driver.
> --
> 2.20.1
>

Daniel Vetter July 7, 2020, 12:13 p.m. UTC | #2

On Tue, Jul 7, 2020 at 1:49 PM Karol Herbst <[e-mail]> wrote:
>
> On Tue, Jul 7, 2020 at 1:38 PM Pekka Paalanen <[e-mail]> wrote:
> >
> > From: Pekka Paalanen <[e-mail]>
> >
> > Set up the expectations on how hot-unplugging a DRM device should look like to
> > userspace.
> >
> > Written by Daniel Vetter's request and largely based on his comments in IRC and
> > from https://lists.freedesktop.org/archives/dri-devel/2020-May/265484.html .
> >
> > A related Wayland protocol change proposal is at
> > https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/35
> >
> > Signed-off-by: Pekka Paalanen <[e-mail]>
> > Reviewed-by: Daniel Vetter <[e-mail]>
> > Reviewed-by: Alex Deucher <[e-mail]>
> > Acked-by: Noralf Trønnes <[e-mail]>
> > Cc: Andrey Grodzovsky <[e-mail]>
> > Cc: Dave Airlie <[e-mail]>
> > Cc: Sean Paul <[e-mail]>
> > Cc: Simon Ser <[e-mail]>
> > Cc: Ben Skeggs <[e-mail]>
> > Cc: Karol Herbst <[e-mail]>
> >
> > ---
> >
> > This is only about laying out plans for the future, not about what
> > drivers do today. We'd just like to be sure the goals are reasonable and
> > everyone is aware of the idea.
> >
> > Thanks,
> > pq
> >
> > v5:
> > - two grammar fixes (Alex)
> > - added R-b/A-b, dropped extra Cc
> >
> > v4:
> > - two typo fixes (Daniel)
> >
> > v3:
> > - update ENODEV doc (Daniel)
> > - clarify existing vs. new mmaps (Andrey)
> > - split into KMS and render/cross sections (Andrey, Daniel)
> > - open() returns ENXIO (open(2) man page)
> > - ioctls may return ENODEV (Andrey, Daniel)
> > - new wayland-protocols MR
> >
> > v2:
> > - mmap reads/writes undefined (Daniel)
> > - make render ioctl behaviour driver-specific (Daniel)
> > - restructure the mmap paragraphs (Daniel)
> > - chardev minor notes (Simon)
> > - open behaviour (Daniel)
> > - DRM leasing behaviour (Daniel)
> > - added links
> >
> > Disclaimer: I am a userspace developer writing for other userspace developers.
> > I took some liberties in defining what should happen without knowing what is
> > actually possible or what existing drivers already implement.
> > ---
> >  Documentation/gpu/drm-uapi.rst | 114 ++++++++++++++++++++++++++++++++-
> >  1 file changed, 113 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> > index 56fec6ed1ad8..9ce51e4f98f4 100644
> > --- a/Documentation/gpu/drm-uapi.rst
> > +++ b/Documentation/gpu/drm-uapi.rst
> > @@ -1,3 +1,5 @@
> > +.. Copyright 2020 DisplayLink (UK) Ltd.
> > +
> >  ===================
> >  Userland interfaces
> >  ===================
> > @@ -162,6 +164,116 @@ other hand, a driver requires shared state between clients which is
> >  visible to user-space and accessible beyond open-file boundaries, they
> >  cannot support render nodes.
> >
> > +Device Hot-Unplug
> > +=================
> > +
> > +.. note::
> > +   The following is the plan. Implementation is not there yet
> > +   (2020 May).
> > +
> > +Graphics devices (display and/or render) may be connected via USB (e.g.
> > +display adapters or docking stations) or Thunderbolt (e.g. eGPU). An end
> > +user is able to hot-unplug this kind of devices while they are being
> > +used, and expects that the very least the machine does not crash. Any
> > +damage from hot-unplugging a DRM device needs to be limited as much as
> > +possible and userspace must be given the chance to handle it if it wants
> > +to. Ideally, unplugging a DRM device still lets a desktop continue to
> > +run, but that is going to need explicit support throughout the whole
> > +graphics stack: from kernel and userspace drivers, through display
> > +servers, via window system protocols, and in applications and libraries.
> > +
> > +Other scenarios that should lead to the same are: unrecoverable GPU
> > +crash, PCI device disappearing off the bus, or forced unbind of a driver
> > +from the physical device.
> > +
> > +In other words, from userspace perspective everything needs to keep on
> > +working more or less, until userspace stops using the disappeared DRM
> > +device and closes it completely. Userspace will learn of the device
> > +disappearance from the device removed uevent, ioctls returning ENODEV
> > +(or driver-specific ioctls returning driver-specific things), or open()
> > +returning ENXIO.
> > +
> > +Only after userspace has closed all relevant DRM device and dmabuf file
> > +descriptors and removed all mmaps, the DRM driver can tear down its
> > +instance for the device that no longer exists. If the same physical
> > +device somehow comes back in the mean time, it shall be a new DRM
> > +device.
> > +
>
> I don't think we can make a general statement like this. Drivers might
> have kworker polling on the device or other asynchronous or repeating
> jobs it might want to get rid of as soon as possible. I think it
> should be fine for the kernel driver to tear down the instance as long
> as it doesn't conflict with the goal of system stability. And usually
> drivers have some kernel side state for clients anyway, so it could be
> handled in this layer instead.

There's two clear bits:
- userspace stuff needs to stay around until the last userspace is
gone, including indirect references (dma_fence, dma_buf, stuff like
that)
- hw stuff must be released right away at unbind time (mmio maps,
interrupts, that kinds of stuff)

Everything in-between is a bit a grey area. Some workers you might
want to stop at unbind and release, for others it might be easier to
not care. This is kinda all up to drivers and where exactly they put
down the line between the userspace visible sw stuff and the hw
related bits.

Since the above is talking about the uapi (this is an addition to
drm-uapi.rst) I think it's totally fine to make the sweeping general
statement, since the uapi stuff really should all stick around, or
stuff starts blowing up at random.
-Daniel

>
> Or maybe I am overlooking something and we really can't do that :/
>
> > +Similar to PIDs, chardev minor numbers are not recycled immediately. A
> > +new DRM device always picks the next free minor number compared to the
> > +previous one allocated, and wraps around when minor numbers are
> > +exhausted.
> > +
> > +The goal raises at least the following requirements for the kernel and
> > +drivers.
> > +
> > +Requirements for KMS UAPI
> > +-------------------------
> > +
> > +- KMS connectors must change their status to disconnected.
> > +
> > +- Legacy modesets and pageflips, and atomic commits, both real and
> > +  TEST_ONLY, and any other ioctls either fail with ENODEV or fake
> > +  success.
> > +
> > +- Pending non-blocking KMS operations deliver the DRM events userspace
> > +  is expecting. This applies also to ioctls that faked success.
> > +
> > +- open() on a device node whose underlying device has disappeared will
> > +  fail with ENXIO.
> > +
> > +- Attempting to create a DRM lease on a disappeared DRM device will
> > +  fail with ENODEV. Existing DRM leases remain and work as listed
> > +  above.
> > +
> > +Requirements for Render and Cross-Device UAPI
> > +---------------------------------------------
> > +
> > +- All GPU jobs that can no longer run must have their fences
> > +  force-signalled to avoid inflicting hangs on userspace.
> > +  The associated error code is ENODEV.
> > +
> > +- Some userspace APIs already define what should happen when the device
> > +  disappears (OpenGL, GL ES: `GL_KHR_robustness`_; `Vulkan`_:
> > +  VK_ERROR_DEVICE_LOST; etc.). DRM drivers are free to implement this
> > +  behaviour the way they see best, e.g. returning failures in
> > +  driver-specific ioctls and handling those in userspace drivers, or
> > +  rely on uevents, and so on.
> > +
> > +- dmabuf which point to memory that has disappeared will either fail to
> > +  import with ENODEV or continue to be successfully imported if it would
> > +  have succeeded before the disappearance. See also about memory maps
> > +  below for already imported dmabufs.
> > +
> > +- Attempting to import a dmabuf to a disappeared device will either fail
> > +  with ENODEV or succeed if it would have succeeded without the
> > +  disappearance.
> > +
> > +- open() on a device node whose underlying device has disappeared will
> > +  fail with ENXIO.
> > +
> > +.. _GL_KHR_robustness: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_robustness.txt
> > +.. _Vulkan: https://www.khronos.org/vulkan/
> > +
> > +Requirements for Memory Maps
> > +----------------------------
> > +
> > +Memory maps have further requirements that apply to both existing maps
> > +and maps created after the device has disappeared. If the underlying
> > +memory disappears, the map is created or modified such that reads and
> > +writes will still complete successfully but the result is undefined.
> > +This applies to both userspace mmap()'d memory and memory pointed to by
> > +dmabuf which might be mapped to other devices (cross-device dmabuf
> > +imports).
> > +
> > +Raising SIGBUS is not an option, because userspace cannot realistically
> > +handle it. Signal handlers are global, which makes them extremely
> > +difficult to use correctly from libraries like those that Mesa produces.
> > +Signal handlers are not composable, you can't have different handlers
> > +for GPU1 and GPU2 from different vendors, and a third handler for
> > +mmapped regular files. Threads cause additional pain with signal
> > +handling as well.
> > +
> >  .. _drm_driver_ioctl:
> >
> >  IOCTL Support on Device Nodes
> > @@ -199,7 +311,7 @@ EPERM/EACCES:
> >          difference between EACCES and EPERM.
> >
> >  ENODEV:
> > -        The device is not (yet) present or fully initialized.
> > +        The device is not present anymore or is not yet fully initialized.
> >
> >  EOPNOTSUPP:
> >          Feature (like PRIME, modesetting, GEM) is not supported by the driver.
> > --
> > 2.20.1
> >
>

Simon Ser July 7, 2020, 12:59 p.m. UTC | #3

On Tuesday, July 7, 2020 1:38 PM, Pekka Paalanen <[e-mail]> wrote:

> From: Pekka Paalanen [e-mail]
>
> Set up the expectations on how hot-unplugging a DRM device should look like to
> userspace.
>
> Written by Daniel Vetter's request and largely based on his comments in IRC and
> from https://lists.freedesktop.org/archives/dri-devel/2020-May/265484.html .
>
> A related Wayland protocol change proposal is at
> https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/35
>
> Signed-off-by: Pekka Paalanen [e-mail]
> Reviewed-by: Daniel Vetter [e-mail]
> Reviewed-by: Alex Deucher [e-mail]
> Acked-by: Noralf Trønnes [e-mail]
> Cc: Andrey Grodzovsky [e-mail]
> Cc: Dave Airlie [e-mail]
> Cc: Sean Paul [e-mail]
> Cc: Simon Ser [e-mail]
> Cc: Ben Skeggs [e-mail]
> Cc: Karol Herbst [e-mail]

From a user-space point-of-view, this sounds fine.

Acked-by: Simon Ser <[e-mail]>

Thanks!

Emil Velikov July 30, 2020, 1:35 p.m. UTC | #4

Hi Pekka,

Thanks for the patch - merged to drm-misc-next.
While applying the patch the following warning popped-up.

-:37: WARNING:SPDX_LICENSE_TAG: Missing or malformed
SPDX-License-Identifier tag in line 1
#37: FILE: Documentation/gpu/drm-uapi.rst:1:
+.. Copyright 2020 DisplayLink (UK) Ltd.
                                   │--

Upon closer look, it seems that the DRM documentation lacks a license.
An SPDX one at least - I haven't done extensive reading through each
individual file.
I guess we should add one - be that GPL-2.0, MIT and/or otherwise.
Since I haven't contributed such that much on the documentation side,
I'll defer the suggestion to the maintainers.

Daniel, Dave, care to do the honours?

Tl;DR: the DRM documentation is missing SPDX license identifier.

Thanks
Emil

Patch

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 56fec6ed1ad8..9ce51e4f98f4 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -1,3 +1,5 @@ 
+.. Copyright 2020 DisplayLink (UK) Ltd.
+
 ===================
 Userland interfaces
 ===================
@@ -162,6 +164,116 @@  other hand, a driver requires shared state between clients which is
 visible to user-space and accessible beyond open-file boundaries, they
 cannot support render nodes.
 
+Device Hot-Unplug
+=================
+
+.. note::
+   The following is the plan. Implementation is not there yet
+   (2020 May).
+
+Graphics devices (display and/or render) may be connected via USB (e.g.
+display adapters or docking stations) or Thunderbolt (e.g. eGPU). An end
+user is able to hot-unplug this kind of devices while they are being
+used, and expects that the very least the machine does not crash. Any
+damage from hot-unplugging a DRM device needs to be limited as much as
+possible and userspace must be given the chance to handle it if it wants
+to. Ideally, unplugging a DRM device still lets a desktop continue to
+run, but that is going to need explicit support throughout the whole
+graphics stack: from kernel and userspace drivers, through display
+servers, via window system protocols, and in applications and libraries.
+
+Other scenarios that should lead to the same are: unrecoverable GPU
+crash, PCI device disappearing off the bus, or forced unbind of a driver
+from the physical device.
+
+In other words, from userspace perspective everything needs to keep on
+working more or less, until userspace stops using the disappeared DRM
+device and closes it completely. Userspace will learn of the device
+disappearance from the device removed uevent, ioctls returning ENODEV
+(or driver-specific ioctls returning driver-specific things), or open()
+returning ENXIO.
+
+Only after userspace has closed all relevant DRM device and dmabuf file
+descriptors and removed all mmaps, the DRM driver can tear down its
+instance for the device that no longer exists. If the same physical
+device somehow comes back in the mean time, it shall be a new DRM
+device.
+
+Similar to PIDs, chardev minor numbers are not recycled immediately. A
+new DRM device always picks the next free minor number compared to the
+previous one allocated, and wraps around when minor numbers are
+exhausted.
+
+The goal raises at least the following requirements for the kernel and
+drivers.
+
+Requirements for KMS UAPI
+-------------------------
+
+- KMS connectors must change their status to disconnected.
+
+- Legacy modesets and pageflips, and atomic commits, both real and
+  TEST_ONLY, and any other ioctls either fail with ENODEV or fake
+  success.
+
+- Pending non-blocking KMS operations deliver the DRM events userspace
+  is expecting. This applies also to ioctls that faked success.
+
+- open() on a device node whose underlying device has disappeared will
+  fail with ENXIO.
+
+- Attempting to create a DRM lease on a disappeared DRM device will
+  fail with ENODEV. Existing DRM leases remain and work as listed
+  above.
+
+Requirements for Render and Cross-Device UAPI
+---------------------------------------------
+
+- All GPU jobs that can no longer run must have their fences
+  force-signalled to avoid inflicting hangs on userspace.
+  The associated error code is ENODEV.
+
+- Some userspace APIs already define what should happen when the device
+  disappears (OpenGL, GL ES: `GL_KHR_robustness`_; `Vulkan`_:
+  VK_ERROR_DEVICE_LOST; etc.). DRM drivers are free to implement this
+  behaviour the way they see best, e.g. returning failures in
+  driver-specific ioctls and handling those in userspace drivers, or
+  rely on uevents, and so on.
+
+- dmabuf which point to memory that has disappeared will either fail to
+  import with ENODEV or continue to be successfully imported if it would
+  have succeeded before the disappearance. See also about memory maps
+  below for already imported dmabufs.
+
+- Attempting to import a dmabuf to a disappeared device will either fail
+  with ENODEV or succeed if it would have succeeded without the
+  disappearance.
+
+- open() on a device node whose underlying device has disappeared will
+  fail with ENXIO.
+
+.. _GL_KHR_robustness: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_robustness.txt
+.. _Vulkan: https://www.khronos.org/vulkan/
+
+Requirements for Memory Maps
+----------------------------
+
+Memory maps have further requirements that apply to both existing maps
+and maps created after the device has disappeared. If the underlying
+memory disappears, the map is created or modified such that reads and
+writes will still complete successfully but the result is undefined.
+This applies to both userspace mmap()'d memory and memory pointed to by
+dmabuf which might be mapped to other devices (cross-device dmabuf
+imports).
+
+Raising SIGBUS is not an option, because userspace cannot realistically
+handle it. Signal handlers are global, which makes them extremely
+difficult to use correctly from libraries like those that Mesa produces.
+Signal handlers are not composable, you can't have different handlers
+for GPU1 and GPU2 from different vendors, and a third handler for
+mmapped regular files. Threads cause additional pain with signal
+handling as well.
+
 .. _drm_driver_ioctl:
 
 IOCTL Support on Device Nodes
@@ -199,7 +311,7 @@  EPERM/EACCES:
         difference between EACCES and EPERM.
 
 ENODEV:
-        The device is not (yet) present or fully initialized.
+        The device is not present anymore or is not yet fully initialized.
 
 EOPNOTSUPP:
         Feature (like PRIME, modesetting, GEM) is not supported by the driver.