summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/drm.tmpl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/drm.tmpl')
-rw-r--r--Documentation/DocBook/drm.tmpl138
1 files changed, 97 insertions, 41 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 7d1278e7a434..ed1d6d289022 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -156,13 +156,6 @@
</para></listitem>
</varlistentry>
<varlistentry>
- <term>DRIVER_USE_MTRR</term>
- <listitem><para>
- Driver uses MTRR interface for mapping memory, the DRM core will
- manage MTRR resources. Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
<term>DRIVER_PCI_DMA</term>
<listitem><para>
Driver is capable of PCI DMA, mapping of PCI DMA buffers to
@@ -195,28 +188,6 @@
</para></listitem>
</varlistentry>
<varlistentry>
- <term>DRIVER_IRQ_VBL</term>
- <listitem><para>Unused. Deprecated.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_DMA_QUEUE</term>
- <listitem><para>
- Should be set if the driver queues DMA requests and completes them
- asynchronously. Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_FB_DMA</term>
- <listitem><para>
- Driver supports DMA to/from the framebuffer, mapping of frambuffer
- DMA buffers to userspace will be supported. Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_IRQ_VBL2</term>
- <listitem><para>Unused. Deprecated.</para></listitem>
- </varlistentry>
- <varlistentry>
<term>DRIVER_GEM</term>
<listitem><para>
Driver use the GEM memory manager.
@@ -234,6 +205,12 @@
Driver implements DRM PRIME buffer sharing.
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>DRIVER_RENDER</term>
+ <listitem><para>
+ Driver supports dedicated render nodes.
+ </para></listitem>
+ </varlistentry>
</variablelist>
</sect3>
<sect3>
@@ -2212,6 +2189,18 @@ void intel_crt_init(struct drm_device *dev)
!Iinclude/drm/drm_rect.h
!Edrivers/gpu/drm/drm_rect.c
</sect2>
+ <sect2>
+ <title>Flip-work Helper Reference</title>
+!Pinclude/drm/drm_flip_work.h flip utils
+!Iinclude/drm/drm_flip_work.h
+!Edrivers/gpu/drm/drm_flip_work.c
+ </sect2>
+ <sect2>
+ <title>VMA Offset Manager</title>
+!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager
+!Edrivers/gpu/drm/drm_vma_manager.c
+!Iinclude/drm/drm_vma_manager.h
+ </sect2>
</sect1>
<!-- Internals: kms properties -->
@@ -2422,18 +2411,18 @@ void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
</abstract>
<para>
The <methodname>firstopen</methodname> method is called by the DRM core
- when an application opens a device that has no other opened file handle.
- Similarly the <methodname>lastclose</methodname> method is called when
- the last application holding a file handle opened on the device closes
- it. Both methods are mostly used for UMS (User Mode Setting) drivers to
- acquire and release device resources which should be done in the
- <methodname>load</methodname> and <methodname>unload</methodname>
- methods for KMS drivers.
+ for legacy UMS (User Mode Setting) drivers only when an application
+ opens a device that has no other opened file handle. UMS drivers can
+ implement it to acquire device resources. KMS drivers can't use the
+ method and must acquire resources in the <methodname>load</methodname>
+ method instead.
</para>
<para>
- Note that the <methodname>lastclose</methodname> method is also called
- at module unload time or, for hot-pluggable devices, when the device is
- unplugged. The <methodname>firstopen</methodname> and
+ Similarly the <methodname>lastclose</methodname> method is called when
+ the last application holding a file handle opened on the device closes
+ it, for both UMS and KMS drivers. Additionally, the method is also
+ called at module unload time or, for hot-pluggable devices, when the
+ device is unplugged. The <methodname>firstopen</methodname> and
<methodname>lastclose</methodname> calls can thus be unbalanced.
</para>
<para>
@@ -2462,7 +2451,12 @@ void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
<para>
The <methodname>lastclose</methodname> method should restore CRTC and
plane properties to default value, so that a subsequent open of the
- device will not inherit state from the previous user.
+ device will not inherit state from the previous user. It can also be
+ used to execute delayed power switching state changes, e.g. in
+ conjunction with the vga-switcheroo infrastructure. Beyond that KMS
+ drivers should not do any further cleanup. Only legacy UMS drivers might
+ need to clean up device state so that the vga console or an independent
+ fbdev driver could take over.
</para>
</sect2>
<sect2>
@@ -2498,7 +2492,6 @@ void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
<programlisting>
.poll = drm_poll,
.read = drm_read,
- .fasync = drm_fasync,
.llseek = no_llseek,
</programlisting>
</para>
@@ -2657,6 +2650,69 @@ int (*resume) (struct drm_device *);</synopsis>
info, since man pages should cover the rest.
</para>
+ <!-- External: render nodes -->
+
+ <sect1>
+ <title>Render nodes</title>
+ <para>
+ DRM core provides multiple character-devices for user-space to use.
+ Depending on which device is opened, user-space can perform a different
+ set of operations (mainly ioctls). The primary node is always created
+ and called <term>card&lt;num&gt;</term>. Additionally, a currently
+ unused control node, called <term>controlD&lt;num&gt;</term> is also
+ created. The primary node provides all legacy operations and
+ historically was the only interface used by userspace. With KMS, the
+ control node was introduced. However, the planned KMS control interface
+ has never been written and so the control node stays unused to date.
+ </para>
+ <para>
+ With the increased use of offscreen renderers and GPGPU applications,
+ clients no longer require running compositors or graphics servers to
+ make use of a GPU. But the DRM API required unprivileged clients to
+ authenticate to a DRM-Master prior to getting GPU access. To avoid this
+ step and to grant clients GPU access without authenticating, render
+ nodes were introduced. Render nodes solely serve render clients, that
+ is, no modesetting or privileged ioctls can be issued on render nodes.
+ Only non-global rendering commands are allowed. If a driver supports
+ render nodes, it must advertise it via the <term>DRIVER_RENDER</term>
+ DRM driver capability. If not supported, the primary node must be used
+ for render clients together with the legacy drmAuth authentication
+ procedure.
+ </para>
+ <para>
+ If a driver advertises render node support, DRM core will create a
+ separate render node called <term>renderD&lt;num&gt;</term>. There will
+ be one render node per device. No ioctls except PRIME-related ioctls
+ will be allowed on this node. Especially <term>GEM_OPEN</term> will be
+ explicitly prohibited. Render nodes are designed to avoid the
+ buffer-leaks, which occur if clients guess the flink names or mmap
+ offsets on the legacy interface. Additionally to this basic interface,
+ drivers must mark their driver-dependent render-only ioctls as
+ <term>DRM_RENDER_ALLOW</term> so render clients can use them. Driver
+ authors must be careful not to allow any privileged ioctls on render
+ nodes.
+ </para>
+ <para>
+ With render nodes, user-space can now control access to the render node
+ via basic file-system access-modes. A running graphics server which
+ authenticates clients on the privileged primary/legacy node is no longer
+ required. Instead, a client can open the render node and is immediately
+ granted GPU access. Communication between clients (or servers) is done
+ via PRIME. FLINK from render node to legacy node is not supported. New
+ clients must not use the insecure FLINK interface.
+ </para>
+ <para>
+ Besides dropping all modeset/global ioctls, render nodes also drop the
+ DRM-Master concept. There is no reason to associate render clients with
+ a DRM-Master as they are independent of any graphics server. Besides,
+ they must work without any running master, anyway.
+ Drivers must be able to run without a master object if they support
+ render nodes. If, on the 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.
+ </para>
+ </sect1>
+
<!-- External: vblank handling -->
<sect1>