Documentation/gpu/drm-uapi.rst

9 addition, drivers export device-specific interfaces for use by userspace
10 drivers & device-aware applications through ioctls and sysfs files.
16 Cover generic ioctls and sysfs layout here. We only need high-level
22 .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
31 .. kernel-doc:: drivers/gpu/drm/drm_auth.c
34 .. kernel-doc:: drivers/gpu/drm/drm_auth.c
37 .. kernel-doc:: include/drm/drm_auth.h
46 .. kernel-doc:: drivers/gpu/drm/drm_lease.c
49 Open-Source Userspace Requirements
53 what the userspace side for new uAPI needs to look like. This section here
57 open-sourced userspace patches, and those patches must be reviewed and ready for
61 hardware, with userspace and kernel by necessity having to work together really
62 closely.  The interfaces, for rendering and modesetting, must be extremely wide
64 them for every possible corner case. This in turn makes it really practically
65 infeasible to differentiate between behaviour that's required by userspace, and
75 - The Linux kernel's "no regression" policy holds in practice only for
76   open-source userspace of the DRM subsystem. DRM developers are perfectly fine
77   if closed-source blob drivers in userspace use the same uAPI as the open
82 - Any new userspace interface must have an open-source implementation as
85 The other reason for requiring open-source userspace is uAPI review. Since the
88 both sides. Making sure that the interface indeed covers the use-case fully
91 - The open-source userspace must not be a toy/test application, but the real
96 - The userspace side must be fully reviewed and tested to the standards of that
97   userspace project. For e.g. mesa this means piglit testcases and review on the
99   job done.  The userspace-side reviewer should also provide an Acked-by on the
101   sufficiently documented and validated for userspace's consumption.
103 - The userspace patches must be against the canonical upstream, not some vendor
107 - The kernel patch can only be merged after all the above requirements are met,
108   but it **must** be merged to either drm-next or drm-misc-next **before** the
116 Linux kernel's guarantee to keep existing userspace running for 10+ years this
117 is already rather painful for the DRM subsystem, with multiple different uAPIs
118 for the same thing co-existing. If we add a few more complete mistakes into the
126 DRM core provides multiple character-devices for user-space to use.
127 Depending on which device is opened, user-space can perform a different
138 make use of a GPU. But the DRM API required unprivileged clients to
139 authenticate to a DRM-Master prior to getting GPU access. To avoid this
143 Only non-global rendering commands are allowed. If a driver supports
145 capability. If not supported, the primary node must be used for render
150 per device. No ioctls except PRIME-related ioctls will be allowed on
151 this node. Especially GEM_OPEN will be explicitly prohibited. For a
152 complete list of driver-independent ioctls that can be used on render
154 nodes are designed to avoid the buffer-leaks, which occur if clients
157 driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render
161 With render nodes, user-space can now control access to the render node
162 via basic file-system access-modes. A running graphics server which
164 required. Instead, a client can open the render node and is immediately
170 DRM-Master concept. There is no reason to associate render clients with
171 a DRM-Master as they are independent of any graphics server. Besides,
175 visible to user-space and accessible beyond open-file boundaries, they
178 Device Hot-Unplug
187 user is able to hot-unplug this kind of devices while they are being
189 damage from hot-unplugging a DRM device needs to be limited as much as
204 (or driver-specific ioctls returning driver-specific things), or open()
209 instance for the device that no longer exists. If the same physical
218 The goal raises at least the following requirements for the kernel and
221 Requirements for KMS UAPI
222 -------------------------
224 - KMS connectors must change their status to disconnected.
226 - Legacy modesets and pageflips, and atomic commits, both real and
230 - Pending non-blocking KMS operations deliver the DRM events userspace
233 - open() on a device node whose underlying device has disappeared will
236 - Attempting to create a DRM lease on a disappeared DRM device will
240 Requirements for Render and Cross-Device UAPI
241 ---------------------------------------------
243 - All GPU jobs that can no longer run must have their fences
244   force-signalled to avoid inflicting hangs on userspace.
247 - Some userspace APIs already define what should happen when the device
251   driver-specific ioctls and handling those in userspace drivers, or
254 - dmabuf which point to memory that has disappeared will either fail to
257   below for already imported dmabufs.
259 - Attempting to import a dmabuf to a disappeared device will either fail
263 - open() on a device node whose underlying device has disappeared will
269 Requirements for Memory Maps
270 ----------------------------
277 dmabuf which might be mapped to other devices (cross-device dmabuf
284 for GPU1 and GPU2 from different vendors, and a third handler for
291 The GPU stack is really complex and is prone to errors, from hardware bugs,
294 section describes the expectations for DRM and usermode drivers when a
300 special policy for blocking guilty applications, if any. Corollary is that
301 debugging a hung GPU context require hardware support to be able to preempt such
305 ------------------
307 The KMD is responsible for checking if the device needs a reset, and to perform
314 dma_fence_set_error() on how to do this and for examples of error codes to use.
317 hardware submissions are restarted after an reset. Error codes are also
318 forwarded from the hardware fence to the scheduler fence to bubble up errors
326 helper for this use case. After a reset, KMD should reject new command
327 submissions for affected contexts.
330 ----------------
340 ----------
347 userspace that doesn't support robust interfaces (like a non-robust
357 extension ``GL_ARB_robustness`` (or ``GL_EXT_robustness`` for OpenGL ES). This
365 Apps using Vulkan should check for ``VK_ERROR_DEVICE_LOST`` for submissions.
370 --------------------------
373 really useful for driver developers to learn more about what caused the reset in
374 the first place. For this, drivers can make use of devcoredump to store relevant
389 re-enumerating the full bus, on which the underlying physical device is sitting)
397 'wedged' device depending on hardware implementation of the underlying physical
399 drivers to decide when they see the need for device recovery and how they want
403 --------------------
405 The driver, before opting for recovery, needs to make sure that the 'wedged'
415 signify the reason for wedging, which can be reported to the application if
419 --------
424 more side-effects. If driver is unsure about recovery or method is unknown
437     bus-reset       unbind + bus reset/re-enumeration + bind
450 ----------------------
456 device of all user context beforehand and set the stage for a clean recovery.
459 -------
463     SUBSYSTEM=="drm", ENV{WEDGED}=="rebind", DEVPATH=="*/drm/card[0-9]",
470     DEVPATH=$(readlink -f /sys/$1/device)
472     DRIVER=$(readlink -f $DEVPATH/driver)
474     echo -n $DEVICE > $DRIVER/unbind
475     echo -n $DEVICE > $DRIVER/bind
478 -------------
481 custom policies around recovery. For example, if the driver supports multiple
482 recovery methods, consumers can opt for the suitable one depending on scenarios
484 have the device available for debugging or telemetry collection and base their
493 .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
497 -------------------------------
506         lookup failure, e.g. for unknown GEM buffer object handles, unknown KMS
511         of VRAM". Sometimes also applies to other limited gpu resources used for
519         Returned for an operation that is valid, but needs more privileges.
520         E.g. root-only or much more common, DRM master-only operations return
531         Remote failure, either a hardware transaction (like i2c), but also used
532         when the exporting driver of a shared dma-buf or fence doesn't support a
542         hardware failures are signalled through the "link status" connector
546         Catch-all for anything that is an invalid argument combination which
554 .. kernel-doc:: include/drm/drm_ioctl.h
557 .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
560 .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
566 Testing Requirements for userspace API
567 --------------------------------------
569 New cross-driver userspace interface extensions, like new IOCTL, new KMS
571 should have driver-agnostic testcases in IGT for that feature, if such a test
572 can be reasonably made using IGT for the target hardware.
575 ---------------------------
581 https://gitlab.freedesktop.org/drm/igt-gpu-tools/.
584 --------------------------
586 VKMS is a software-only model of a KMS driver that is useful for testing
587 and for running compositors. VKMS aims to enable a virtual display without
588 the need for a hardware display capability. These characteristics made VKMS
589 a perfect tool for validating the DRM core behavior and also support the
600 It's possible to run the IGT-tests in a VM in two ways:
606 the host machine to run igt-tests. This example uses virtme::
608 	$ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto
610 Run the igt-tests in the guest machine. This example runs the 'kms_flip'
613 	$ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v
616 (-p option). It creates an HTML summary of the test results and saves
617 them in the folder "igt-gpu-tools/results". It executes only the igt-tests
618 matching the -t option.
621 -------------------
623 .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
626 .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
630 ---------------
632 .. kernel-doc:: include/drm/drm_debugfs.h
635 .. kernel-doc:: drivers/gpu/drm/drm_debugfs.c
641 .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c
644 .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c
659     This was only used for user-mode-settind drivers around modesetting
663     call this any more since with kernel mode setting it is a no-op.
668 .. kernel-doc:: include/uapi/drm/drm_mode.h
674 ----------
677 The index is used in cases where a densely packed identifier for a CRTC is
678 needed, for instance a bitmask of CRTC's. The member possible_crtcs of struct
684 .. kernel-doc:: include/uapi/drm/drm.h
687 .. kernel-doc:: include/uapi/drm/drm_mode.h
691 dma-buf interoperability
694 Please see Documentation/userspace-api/dma-buf-alloc-exchange.rst for
695 information on how dma-buf is integrated and exposed within DRM.