diff options
Diffstat (limited to 'Documentation/DocBook/drm.tmpl')
| -rw-r--r-- | Documentation/DocBook/drm.tmpl | 138 |
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<num></term>. Additionally, a currently + unused control node, called <term>controlD<num></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<num></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> |