</address>
</affiliation>
</author>
+ <author>
+ <firstname>Daniel</firstname>
+ <surname>Vetter</surname>
+ <contrib>Contributions all over the place</contrib>
+ <affiliation>
+ <orgname>Intel Corporation</orgname>
+ <address>
+ <email>daniel.vetter@ffwll.ch</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
<copyright>
<year>2008-2009</year>
- <year>2012</year>
+ <year>2013-2014</year>
<holder>Intel Corporation</holder>
+ </copyright>
+ <copyright>
+ <year>2012</year>
<holder>Laurent Pinchart</holder>
</copyright>
<toc></toc>
- <!-- Introduction -->
+<part id="drmCore">
+ <title>DRM Core</title>
+ <partintro>
+ <para>
+ This first part of the DRM Developer's Guide documents core DRM code,
+ helper libraries for writting drivers and generic userspace interfaces
+ exposed by DRM drivers.
+ </para>
+ </partintro>
<chapter id="drmIntroduction">
<title>Introduction</title>
<para>
The <methodname>load</methodname> method is the driver and device
initialization entry point. The method is responsible for allocating and
- initializing driver private data, specifying supported performance
- counters, performing resource allocation and mapping (e.g. acquiring
+ initializing driver private data, performing resource allocation and
+ mapping (e.g. acquiring
clocks, mapping registers or allocating command buffers), initializing
the memory manager (<xref linkend="drm-memory-management"/>), installing
the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up
their <methodname>load</methodname> method called with flags to 0.
</para>
<sect3>
- <title>Driver Private & Performance Counters</title>
+ <title>Driver Private Data</title>
<para>
The driver private hangs off the main
<structname>drm_device</structname> structure and can be used for
<structname>drm_device</structname>.<structfield>dev_priv</structfield>
set to NULL when the driver is unloaded.
</para>
- <para>
- DRM supports several counters which were used for rough performance
- characterization. This stat counter system is deprecated and should not
- be used. If performance monitoring is desired, the developer should
- investigate and potentially enhance the kernel perf and tracing
- infrastructure to export GPU related performance information for
- consumption by performance monitoring tools and applications.
- </para>
</sect3>
<sect3 id="drm-irq-registration">
<title>IRQ Registration</title>
respectively. The conversion is handled by the DRM core without any
driver-specific support.
</para>
- <para>
- Similar to global names, GEM file descriptors are also used to share GEM
- objects across processes. They offer additional security: as file
- descriptors must be explicitly sent over UNIX domain sockets to be shared
- between applications, they can't be guessed like the globally unique GEM
- names.
- </para>
- <para>
- Drivers that support GEM file descriptors, also known as the DRM PRIME
- API, must set the DRIVER_PRIME bit in the struct
- <structname>drm_driver</structname>
- <structfield>driver_features</structfield> field, and implement the
- <methodname>prime_handle_to_fd</methodname> and
- <methodname>prime_fd_to_handle</methodname> operations.
- </para>
- <para>
- <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
- struct drm_file *file_priv, uint32_t handle,
- uint32_t flags, int *prime_fd);
- int (*prime_fd_to_handle)(struct drm_device *dev,
- struct drm_file *file_priv, int prime_fd,
- uint32_t *handle);</synopsis>
- Those two operations convert a handle to a PRIME file descriptor and
- vice versa. Drivers must use the kernel dma-buf buffer sharing framework
- to manage the PRIME file descriptors.
- </para>
- <para>
- While non-GEM drivers must implement the operations themselves, GEM
- drivers must use the <function>drm_gem_prime_handle_to_fd</function>
- and <function>drm_gem_prime_fd_to_handle</function> helper functions.
- Those helpers rely on the driver
- <methodname>gem_prime_export</methodname> and
- <methodname>gem_prime_import</methodname> operations to create a dma-buf
- instance from a GEM object (dma-buf exporter role) and to create a GEM
- object from a dma-buf instance (dma-buf importer role).
- </para>
- <para>
- <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
- struct drm_gem_object *obj,
- int flags);
- struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
- struct dma_buf *dma_buf);</synopsis>
- These two operations are mandatory for GEM drivers that support DRM
- PRIME.
- </para>
- <sect4>
- <title>DRM PRIME Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers
- </sect4>
+ <para>
+ GEM also supports buffer sharing with dma-buf file descriptors through
+ PRIME. GEM-based drivers must use the provided helpers functions to
+ implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />.
+ Since sharing file descriptors is inherently more secure than the
+ easily guessable and global GEM names it is the preferred buffer
+ sharing mechanism. Sharing buffers through GEM names is only supported
+ for legacy userspace. Furthermore PRIME also allows cross-device
+ buffer sharing since it is based on dma-bufs.
+ </para>
</sect3>
<sect3 id="drm-gem-objects-mapping">
<title>GEM Objects Mapping</title>
abstracted from the client in libdrm.
</para>
</sect3>
- <sect2>
+ <sect3>
<title>GEM Function Reference</title>
!Edrivers/gpu/drm/drm_gem.c
+ </sect3>
</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>
+ <sect2 id="drm-prime-support">
+ <title>PRIME Buffer Sharing</title>
+ <para>
+ PRIME is the cross device buffer sharing framework in drm, originally
+ created for the OPTIMUS range of multi-gpu platforms. To userspace
+ PRIME buffers are dma-buf based file descriptors.
+ </para>
+ <sect3>
+ <title>Overview and Driver Interface</title>
+ <para>
+ Similar to GEM global names, PRIME file descriptors are
+ also used to share buffer objects across processes. They offer
+ additional security: as file descriptors must be explicitly sent over
+ UNIX domain sockets to be shared between applications, they can't be
+ guessed like the globally unique GEM names.
+ </para>
+ <para>
+ Drivers that support the PRIME
+ API must set the DRIVER_PRIME bit in the struct
+ <structname>drm_driver</structname>
+ <structfield>driver_features</structfield> field, and implement the
+ <methodname>prime_handle_to_fd</methodname> and
+ <methodname>prime_fd_to_handle</methodname> operations.
+ </para>
+ <para>
+ <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
+ struct drm_file *file_priv, uint32_t handle,
+ uint32_t flags, int *prime_fd);
+int (*prime_fd_to_handle)(struct drm_device *dev,
+ struct drm_file *file_priv, int prime_fd,
+ uint32_t *handle);</synopsis>
+ Those two operations convert a handle to a PRIME file descriptor and
+ vice versa. Drivers must use the kernel dma-buf buffer sharing framework
+ to manage the PRIME file descriptors. Similar to the mode setting
+ API PRIME is agnostic to the underlying buffer object manager, as
+ long as handles are 32bit unsinged integers.
+ </para>
+ <para>
+ While non-GEM drivers must implement the operations themselves, GEM
+ drivers must use the <function>drm_gem_prime_handle_to_fd</function>
+ and <function>drm_gem_prime_fd_to_handle</function> helper functions.
+ Those helpers rely on the driver
+ <methodname>gem_prime_export</methodname> and
+ <methodname>gem_prime_import</methodname> operations to create a dma-buf
+ instance from a GEM object (dma-buf exporter role) and to create a GEM
+ object from a dma-buf instance (dma-buf importer role).
+ </para>
+ <para>
+ <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
+ struct drm_gem_object *obj,
+ int flags);
+struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
+ struct dma_buf *dma_buf);</synopsis>
+ These two operations are mandatory for GEM drivers that support
+ PRIME.
+ </para>
+ </sect3>
+ <sect3>
+ <title>PRIME Helper Functions</title>
+!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>PRIME Function References</title>
+!Edrivers/gpu/drm/drm_prime.c
+ </sect2>
+ <sect2>
+ <title>DRM MM Range Allocator</title>
+ <sect3>
+ <title>Overview</title>
+!Pdrivers/gpu/drm/drm_mm.c Overview
+ </sect3>
+ <sect3>
+ <title>LRU Scan/Eviction Support</title>
+!Pdrivers/gpu/drm/drm_mm.c lru scan roaster
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>DRM MM Range Allocator Function References</title>
+!Edrivers/gpu/drm/drm_mm.c
+!Iinclude/drm/drm_mm.h
</sect2>
</sect1>
<para>Mode setting functions.</para>
</listitem>
</itemizedlist>
+ <sect2>
+ <title>Display Modes Function Reference</title>
+!Edrivers/gpu/drm/drm_modes.c
+ </sect2>
<sect2>
<title>Frame Buffer Creation</title>
<synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
This operation is called with the mode config lock held.
</para>
<note><para>
- FIXME: How should set_config interact with DPMS? If the CRTC is
- suspended, should it be resumed?
+ Note that the drm core has no notion of restoring the mode setting
+ state after resume, since all resume handling is in the full
+ responsibility of the driver. The common mode setting helper library
+ though provides a helper which can be used for this:
+ <function>drm_helper_resume_force_mode</function>.
</para></note>
</sect4>
<sect4>
!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
+ <title>HDMI Infoframes Helper Reference</title>
+ <para>
+ Strictly speaking this is not a DRM helper library but generally useable
+ by any driver interfacing with HDMI outputs like v4l or alsa drivers.
+ But it nicely fits into the overall topic of mode setting helper
+ libraries and hence is also included here.
+ </para>
+!Iinclude/linux/hdmi.h
+!Edrivers/video/hdmi.c
</sect2>
</sect1>
</para>
</sect2>
</sect1>
-
<sect1>
- <title>Command submission & fencing</title>
+ <title>Legacy Support Code</title>
<para>
- This should cover a few device-specific command submission
- implementations.
+ The section very brievely covers some of the old legacy support code which
+ is only used by old DRM drivers which have done a so-called shadow-attach
+ to the underlying device instead of registering as a real driver. This
+ also includes some of the old generic buffer mangement and command
+ submission code. Do not use any of this in new and modern drivers.
</para>
- </sect1>
- <!-- Internals: suspend/resume -->
-
- <sect1>
- <title>Suspend/Resume</title>
- <para>
- The DRM core provides some suspend/resume code, but drivers wanting full
- suspend/resume support should provide save() and restore() functions.
- These are called at suspend, hibernate, or resume time, and should perform
- any state save or restore required by your device across suspend or
- hibernate states.
- </para>
- <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
-int (*resume) (struct drm_device *);</synopsis>
- <para>
- Those are legacy suspend and resume methods. New driver should use the
- power management interface provided by their bus type (usually through
- the struct <structname>device_driver</structname> dev_pm_ops) and set
- these methods to NULL.
- </para>
- </sect1>
+ <sect2>
+ <title>Legacy Suspend/Resume</title>
+ <para>
+ The DRM core provides some suspend/resume code, but drivers wanting full
+ suspend/resume support should provide save() and restore() functions.
+ These are called at suspend, hibernate, or resume time, and should perform
+ any state save or restore required by your device across suspend or
+ hibernate states.
+ </para>
+ <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
+ int (*resume) (struct drm_device *);</synopsis>
+ <para>
+ Those are legacy suspend and resume methods which
+ <emphasis>only</emphasis> work with the legacy shadow-attach driver
+ registration functions. New driver should use the power management
+ interface provided by their bus type (usually through
+ the struct <structname>device_driver</structname> dev_pm_ops) and set
+ these methods to NULL.
+ </para>
+ </sect2>
- <sect1>
- <title>DMA services</title>
- <para>
- This should cover how DMA mapping etc. is supported by the core.
- These functions are deprecated and should not be used.
- </para>
+ <sect2>
+ <title>Legacy DMA Services</title>
+ <para>
+ This should cover how DMA mapping etc. is supported by the core.
+ These functions are deprecated and should not be used.
+ </para>
+ </sect2>
</sect1>
</chapter>
</sect1>
</chapter>
+</part>
+<part id="drmDrivers">
+ <title>DRM Drivers</title>
- <!-- API reference -->
+ <partintro>
+ <para>
+ This second part of the DRM Developer's Guide documents driver code,
+ implementation details and also all the driver-specific userspace
+ interfaces. Especially since all hardware-acceleration interfaces to
+ userspace are driver specific for efficiency and other reasons these
+ interfaces can be rather substantial. Hence every driver has its own
+ chapter.
+ </para>
+ </partintro>
- <appendix id="drmDriverApi">
- <title>DRM Driver API</title>
+ <chapter id="drmI915">
+ <title>drm/i915 Intel GFX Driver</title>
<para>
- Include auto-generated API reference here (need to reference it
- from paragraphs above too).
+ The drm/i915 driver supports all (with the exception of some very early
+ models) integrated GFX chipsets with both Intel display and rendering
+ blocks. This excludes a set of SoC platforms with an SGX rendering unit,
+ those have basic support through the gma500 drm driver.
</para>
- </appendix>
+ <sect1>
+ <title>Display Hardware Handling</title>
+ <para>
+ This section covers everything related to the display hardware including
+ the mode setting infrastructure, plane, sprite and cursor handling and
+ display, output probing and related topics.
+ </para>
+ <sect2>
+ <title>Mode Setting Infrastructure</title>
+ <para>
+ The i915 driver is thus far the only DRM driver which doesn't use the
+ common DRM helper code to implement mode setting sequences. Thus it
+ has its own tailor-made infrastructure for executing a display
+ configuration change.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Plane Configuration</title>
+ <para>
+ This section covers plane configuration and composition with the
+ primary plane, sprites, cursors and overlays. This includes the
+ infrastructure to do atomic vsync'ed updates of all this state and
+ also tightly coupled topics like watermark setup and computation,
+ framebuffer compression and panel self refresh.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Output Probing</title>
+ <para>
+ This section covers output probing and related infrastructure like the
+ hotplug interrupt storm detection and mitigation code. Note that the
+ i915 driver still uses most of the common DRM helper code for output
+ probing, so those sections fully apply.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Memory Management and Command Submission</title>
+ <para>
+ This sections covers all things related to the GEM implementation in the
+ i915 driver.
+ </para>
+ </sect1>
+ </chapter>
+</part>
</book>
projects / firefly-linux-kernel-4.4.55.git / blobdiff