aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorDavid Herrmann <dh.herrmann@gmail.com>2013-08-25 12:29:00 -0400
committerDave Airlie <airlied@gmail.com>2013-08-29 18:43:57 -0400
commit1793126fcebd7c18834f95d43b55e387a8803aa8 (patch)
tree4e8dddc699ac1fec52b3bb47ca6116d2654abc16 /Documentation/DocBook
parent6cb3b7f1c013fd4bea41e16ee557bcb2f1561787 (diff)
drm: implement experimental render nodes
Render nodes provide an API for userspace to use non-privileged GPU commands without any running DRM-Master. It is useful for offscreen rendering, GPGPU clients, and normal render clients which do not perform modesetting. Compared to legacy clients, render clients no longer need any authentication to perform client ioctls. Instead, user-space controls render/client access to GPUs via filesystem access-modes on the render-node. Once a render-node was opened, a client has full access to the client/render operations on the GPU. However, no modesetting or ioctls that affect global state are allowed on render nodes. To prevent privilege-escalation, drivers must explicitly state that they support render nodes. They must mark their render-only ioctls as DRM_RENDER_ALLOW so render clients can use them. Furthermore, they must support clients without any attached master. If filesystem access-modes are not enough for fine-grained access control to render nodes (very unlikely, considering the versaitlity of FS-ACLs), you may still fall-back to fd-passing from server to client (which allows arbitrary access-control). However, note that revoking access is currently impossible and unlikely to get implemented. Note: Render clients no longer have any associated DRM-Master as they are supposed to be independent of any server state. DRM core highly depends on file_priv->master to be non-NULL for modesetting/ctx/etc. commands. Therefore, drivers must be very careful to not require DRM-Master if they support DRIVER_RENDER. So far render-nodes are protected by "drm_rnodes". As long as this module-parameter is not set to 1, a driver will not create render nodes. This allows us to experiment with the API a bit before we stabilize it. v2: drop insecure GEM_FLINK to force use of dmabuf Signed-off-by: David Herrmann <dh.herrmann@gmail.com> Signed-off-by: Dave Airlie <airlied@redhat.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/drm.tmpl69
1 files changed, 69 insertions, 0 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 9fc8ed4ac0f4..ed1d6d289022 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -205,6 +205,12 @@
205 Driver implements DRM PRIME buffer sharing. 205 Driver implements DRM PRIME buffer sharing.
206 </para></listitem> 206 </para></listitem>
207 </varlistentry> 207 </varlistentry>
208 <varlistentry>
209 <term>DRIVER_RENDER</term>
210 <listitem><para>
211 Driver supports dedicated render nodes.
212 </para></listitem>
213 </varlistentry>
208 </variablelist> 214 </variablelist>
209 </sect3> 215 </sect3>
210 <sect3> 216 <sect3>
@@ -2644,6 +2650,69 @@ int (*resume) (struct drm_device *);</synopsis>
2644 info, since man pages should cover the rest. 2650 info, since man pages should cover the rest.
2645 </para> 2651 </para>
2646 2652
2653 <!-- External: render nodes -->
2654
2655 <sect1>
2656 <title>Render nodes</title>
2657 <para>
2658 DRM core provides multiple character-devices for user-space to use.
2659 Depending on which device is opened, user-space can perform a different
2660 set of operations (mainly ioctls). The primary node is always created
2661 and called <term>card&lt;num&gt;</term>. Additionally, a currently
2662 unused control node, called <term>controlD&lt;num&gt;</term> is also
2663 created. The primary node provides all legacy operations and
2664 historically was the only interface used by userspace. With KMS, the
2665 control node was introduced. However, the planned KMS control interface
2666 has never been written and so the control node stays unused to date.
2667 </para>
2668 <para>
2669 With the increased use of offscreen renderers and GPGPU applications,
2670 clients no longer require running compositors or graphics servers to
2671 make use of a GPU. But the DRM API required unprivileged clients to
2672 authenticate to a DRM-Master prior to getting GPU access. To avoid this
2673 step and to grant clients GPU access without authenticating, render
2674 nodes were introduced. Render nodes solely serve render clients, that
2675 is, no modesetting or privileged ioctls can be issued on render nodes.
2676 Only non-global rendering commands are allowed. If a driver supports
2677 render nodes, it must advertise it via the <term>DRIVER_RENDER</term>
2678 DRM driver capability. If not supported, the primary node must be used
2679 for render clients together with the legacy drmAuth authentication
2680 procedure.
2681 </para>
2682 <para>
2683 If a driver advertises render node support, DRM core will create a
2684 separate render node called <term>renderD&lt;num&gt;</term>. There will
2685 be one render node per device. No ioctls except PRIME-related ioctls
2686 will be allowed on this node. Especially <term>GEM_OPEN</term> will be
2687 explicitly prohibited. Render nodes are designed to avoid the
2688 buffer-leaks, which occur if clients guess the flink names or mmap
2689 offsets on the legacy interface. Additionally to this basic interface,
2690 drivers must mark their driver-dependent render-only ioctls as
2691 <term>DRM_RENDER_ALLOW</term> so render clients can use them. Driver
2692 authors must be careful not to allow any privileged ioctls on render
2693 nodes.
2694 </para>
2695 <para>
2696 With render nodes, user-space can now control access to the render node
2697 via basic file-system access-modes. A running graphics server which
2698 authenticates clients on the privileged primary/legacy node is no longer
2699 required. Instead, a client can open the render node and is immediately
2700 granted GPU access. Communication between clients (or servers) is done
2701 via PRIME. FLINK from render node to legacy node is not supported. New
2702 clients must not use the insecure FLINK interface.
2703 </para>
2704 <para>
2705 Besides dropping all modeset/global ioctls, render nodes also drop the
2706 DRM-Master concept. There is no reason to associate render clients with
2707 a DRM-Master as they are independent of any graphics server. Besides,
2708 they must work without any running master, anyway.
2709 Drivers must be able to run without a master object if they support
2710 render nodes. If, on the other hand, a driver requires shared state
2711 between clients which is visible to user-space and accessible beyond
2712 open-file boundaries, they cannot support render nodes.
2713 </para>
2714 </sect1>
2715
2647 <!-- External: vblank handling --> 2716 <!-- External: vblank handling -->
2648 2717
2649 <sect1> 2718 <sect1>