<!DOCTYPE html>   <html class="no-js" lang="en" >  <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Kernel Mode Setting (KMS) — The Linux Kernel documentation</title> <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" /> <link rel="index" title="Index" href="../genindex.html"/> <link rel="search" title="Search" href="../search.html"/> <link rel="top" title="The Linux Kernel documentation" href="../index.html"/> <link rel="up" title="Linux GPU Driver Developer’s Guide" href="index.html"/> <link rel="next" title="Mode Setting Helper Functions" href="drm-kms-helpers.html"/> <link rel="prev" title="DRM Memory Management" href="drm-mm.html"/> <script src="../_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav" role="document"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="../index.html" class="icon icon-home"> The Linux Kernel </a> <div class="version"> 4.16.0-rc4 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <ul> <li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Linux kernel licensing rules</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">The Linux kernel user’s and administrator’s guide</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">The Linux kernel user-space API guide</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../process/index.html">Working with the kernel development community</a></li> <li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools for the kernel</a></li> <li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">How to write kernel documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Kernel Hacking Guides</a></li> <li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Kernel Maintainer Handbook</a></li> </ul> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">The Linux driver implementer’s API guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../media/index.html">Linux Media Subsystem Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../networking/index.html">Linux Networking Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../input/index.html">The Linux Input Documentation</a></li> <li class="toctree-l1 current"><a class="reference internal" href="index.html">Linux GPU Driver Developer’s Guide</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li> <li class="toctree-l2"><a class="reference internal" href="drm-internals.html">DRM Internals</a></li> <li class="toctree-l2"><a class="reference internal" href="drm-mm.html">DRM Memory Management</a></li> <li class="toctree-l2 current"><a class="current reference internal" href="#">Kernel Mode Setting (KMS)</a><ul> <li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a></li> <li class="toctree-l3"><a class="reference internal" href="#kms-core-structures-and-functions">KMS Core Structures and Functions</a></li> <li class="toctree-l3"><a class="reference internal" href="#modeset-base-object-abstraction">Modeset Base Object Abstraction</a></li> <li class="toctree-l3"><a class="reference internal" href="#atomic-mode-setting">Atomic Mode Setting</a><ul> <li class="toctree-l4"><a class="reference internal" href="#handling-driver-private-state">Handling Driver Private State</a></li> <li class="toctree-l4"><a class="reference internal" href="#atomic-mode-setting-function-reference">Atomic Mode Setting Function Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#crtc-abstraction">CRTC Abstraction</a><ul> <li class="toctree-l4"><a class="reference internal" href="#crtc-functions-reference">CRTC Functions Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#frame-buffer-abstraction">Frame Buffer Abstraction</a><ul> <li class="toctree-l4"><a class="reference internal" href="#frame-buffer-functions-reference">Frame Buffer Functions Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#drm-format-handling">DRM Format Handling</a></li> <li class="toctree-l3"><a class="reference internal" href="#dumb-buffer-objects">Dumb Buffer Objects</a></li> <li class="toctree-l3"><a class="reference internal" href="#plane-abstraction">Plane Abstraction</a><ul> <li class="toctree-l4"><a class="reference internal" href="#plane-functions-reference">Plane Functions Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#display-modes-function-reference">Display Modes Function Reference</a></li> <li class="toctree-l3"><a class="reference internal" href="#connector-abstraction">Connector Abstraction</a><ul> <li class="toctree-l4"><a class="reference internal" href="#connector-functions-reference">Connector Functions Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#encoder-abstraction">Encoder Abstraction</a><ul> <li class="toctree-l4"><a class="reference internal" href="#encoder-functions-reference">Encoder Functions Reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#kms-initialization-and-cleanup">KMS Initialization and Cleanup</a><ul> <li class="toctree-l4"><a class="reference internal" href="#crtcs-struct-drm-crtc">CRTCs (<code class="docutils literal">struct drm_crtc</code>)</a></li> <li class="toctree-l4"><a class="reference internal" href="#cleanup">Cleanup</a></li> <li class="toctree-l4"><a class="reference internal" href="#output-discovery-and-initialization-example">Output discovery and initialization example</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#kms-locking">KMS Locking</a></li> <li class="toctree-l3"><a class="reference internal" href="#kms-properties">KMS Properties</a><ul> <li class="toctree-l4"><a class="reference internal" href="#property-types-and-blob-property-support">Property Types and Blob Property Support</a></li> <li class="toctree-l4"><a class="reference internal" href="#standard-connector-properties">Standard Connector Properties</a></li> <li class="toctree-l4"><a class="reference internal" href="#plane-composition-properties">Plane Composition Properties</a></li> <li class="toctree-l4"><a class="reference internal" href="#color-management-properties">Color Management Properties</a></li> <li class="toctree-l4"><a class="reference internal" href="#tile-group-property">Tile Group Property</a></li> <li class="toctree-l4"><a class="reference internal" href="#explicit-fencing-properties">Explicit Fencing Properties</a></li> <li class="toctree-l4"><a class="reference internal" href="#existing-kms-properties">Existing KMS Properties</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#vertical-blanking">Vertical Blanking</a><ul> <li class="toctree-l4"><a class="reference internal" href="#vertical-blanking-and-interrupt-handling-functions-reference">Vertical Blanking and Interrupt Handling Functions Reference</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="drm-kms-helpers.html">Mode Setting Helper Functions</a></li> <li class="toctree-l2"><a class="reference internal" href="drm-uapi.html">Userland interfaces</a></li> <li class="toctree-l2"><a class="reference internal" href="i915.html">drm/i915 Intel GFX Driver</a></li> <li class="toctree-l2"><a class="reference internal" href="meson.html">drm/meson AmLogic Meson Video Processing Unit</a></li> <li class="toctree-l2"><a class="reference internal" href="pl111.html">drm/pl111 ARM PrimeCell PL111 CLCD Driver</a></li> <li class="toctree-l2"><a class="reference internal" href="tegra.html">drm/tegra NVIDIA Tegra GPU and display driver</a></li> <li class="toctree-l2"><a class="reference internal" href="tinydrm.html">drm/tinydrm Driver library</a></li> <li class="toctree-l2"><a class="reference internal" href="tve200.html">drm/tve200 Faraday TV Encoder 200</a></li> <li class="toctree-l2"><a class="reference internal" href="vc4.html">drm/vc4 Broadcom VC4 Graphics Driver</a></li> <li class="toctree-l2"><a class="reference internal" href="vga-switcheroo.html">VGA Switcheroo</a></li> <li class="toctree-l2"><a class="reference internal" href="vgaarbiter.html">VGA Arbiter</a></li> <li class="toctree-l2"><a class="reference internal" href="bridge/dw-hdmi.html">drm/bridge/dw-hdmi Synopsys DesignWare HDMI Controller</a></li> <li class="toctree-l2"><a class="reference internal" href="todo.html">TODO list</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../security/index.html">Security Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../sound/index.html">Linux Sound Subsystem Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../crypto/index.html">Linux Kernel Crypto API</a></li> <li class="toctree-l1"><a class="reference internal" href="../filesystems/index.html">Linux Filesystems API</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../sh/index.html">SuperH Interfaces Guide</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../translations/ko_KR/index.html">Korean translations</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../translations/zh_CN/index.html">Chinese translations</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../translations/ja_JP/index.html">Japanese translations</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> <a href="../index.html">The Linux Kernel</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html">Docs</a> »</li> <li><a href="index.html">Linux GPU Driver Developer’s Guide</a> »</li> <li>Kernel Mode Setting (KMS)</li> <li class="wy-breadcrumbs-aside"> <a href="../_sources/gpu/drm-kms.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="kernel-mode-setting-kms"> <h1>Kernel Mode Setting (KMS)<a class="headerlink" href="#kernel-mode-setting-kms" title="Permalink to this headline">¶</a></h1> Drivers must initialize the mode setting core by calling <a class="reference internal" href="#c.drm_mode_config_init" title="drm_mode_config_init"><code class="xref c c-func docutils literal">drm_mode_config_init()</code></a> on the DRM device. The function initializes the <code class="xref c c-type docutils literal">struct drm_device</code> mode_config field and never fails. Once done, mode configuration must be setup by initializing the following fields. <ul class="simple"> <li>int min_width, min_height; int max_width, max_height; Minimum and maximum width and height of the frame buffers in pixel units.</li> <li>struct drm_mode_config_funcs *funcs; Mode setting functions.</li> </ul> <div class="section" id="overview"> <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2> <div class="figure" id="id5"> <img alt="KMS Display Pipeline" src="../_images/DOT-dade12aa9127c64406e41cdf8d7f80694c134db2.svg" />KMS Display Pipeline Overview </div> The basic object structure KMS presents to userspace is fairly simple. Framebuffers (represented by <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">struct drm_framebuffer</code></a>, see <a class="reference internal" href="#frame-buffer-abstraction">Frame Buffer Abstraction</a>) feed into planes. One or more (or even no) planes feed their pixel data into a CRTC (represented by <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>, see <a class="reference internal" href="#crtc-abstraction">CRTC Abstraction</a>) for blending. The precise blending step is explained in more detail in <a class="reference internal" href="#plane-composition-properties">Plane Composition Properties</a> and related chapters. For the output routing the first step is encoders (represented by <a class="reference internal" href="#c.drm_encoder" title="drm_encoder"><code class="xref c c-type docutils literal">struct drm_encoder</code></a>, see <a class="reference internal" href="#encoder-abstraction">Encoder Abstraction</a>). Those are really just internal artifacts of the helper libraries used to implement KMS drivers. Besides that they make it unecessarily more complicated for userspace to figure out which connections between a CRTC and a connector are possible, and what kind of cloning is supported, they serve no purpose in the userspace API. Unfortunately encoders have been exposed to userspace, hence can’t remove them at this point. Futhermore the exposed restrictions are often wrongly set by drivers, and in many cases not powerful enough to express the real restrictions. A CRTC can be connected to multiple encoders, and for an active CRTC there must be at least one encoder. The final, and real, endpoint in the display chain is the connector (represented by <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a>, see <a class="reference internal" href="#connector-abstraction">Connector Abstraction</a>). Connectors can have different possible encoders, but the kernel driver selects which encoder to use for each connector. The use case is DVI, which could switch between an analog and a digital encoder. Encoders can also drive multiple different connectors. There is exactly one active connector for every active encoder. Internally the output pipeline is a bit more complex and matches today’s hardware more closely: <div class="figure" id="id6"> <img alt="KMS Output Pipeline" src="../_images/DOT-6445c75fc4859992454fd377127d4d309e82f09a.svg" />KMS Output Pipeline </div> Internally two additional helper objects come into play. First, to be able to share code for encoders (sometimes on the same SoC, sometimes off-chip) one or more <a class="reference internal" href="drm-kms-helpers.html#drm-bridges">Bridges</a> (represented by <a class="reference internal" href="drm-kms-helpers.html#c.drm_bridge" title="drm_bridge"><code class="xref c c-type docutils literal">struct drm_bridge</code></a>) can be linked to an encoder. This link is static and cannot be changed, which means the cross-bar (if there is any) needs to be mapped between the CRTC and any encoders. Often for drivers with bridges there’s no code left at the encoder level. Atomic drivers can leave out all the encoder callbacks to essentially only leave a dummy routing object behind, which is needed for backwards compatibility since encoders are exposed to userspace. The second object is for panels, represented by <a class="reference internal" href="drm-kms-helpers.html#c.drm_panel" title="drm_panel"><code class="xref c c-type docutils literal">struct drm_panel</code></a>, see <a class="reference internal" href="drm-kms-helpers.html#drm-panel-helper">Panel Helper Reference</a>. Panels do not have a fixed binding point, but are generally linked to the driver private structure that embeds <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a>. Note that currently the bridge chaining and interactions with connectors and panels are still in-flux and not really fully sorted out yet. </div> <div class="section" id="kms-core-structures-and-functions"> <h2>KMS Core Structures and Functions<a class="headerlink" href="#kms-core-structures-and-functions" title="Permalink to this headline">¶</a></h2> <dl class="type"> <dt id="c.drm_mode_config_funcs"> struct <code class="descname">drm_mode_config_funcs</code><a class="headerlink" href="#c.drm_mode_config_funcs" title="Permalink to this definition">¶</a></dt> <dd>basic driver provided mode setting functions </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_mode_config_funcs { struct drm_framebuffer *(*fb_create)(struct drm_device *dev,struct drm_file *file_priv, const struct drm_mode_fb_cmd2 *mode_cmd); const struct drm_format_info *(*get_format_info)(const struct drm_mode_fb_cmd2 *mode_cmd); void (*output_poll_changed)(struct drm_device *dev); int (*atomic_check)(struct drm_device *dev, struct drm_atomic_state *state); int (*atomic_commit)(struct drm_device *dev,struct drm_atomic_state *state, bool nonblock); struct drm_atomic_state *(*atomic_state_alloc)(struct drm_device *dev); void (*atomic_state_clear)(struct drm_atomic_state *state); void (*atomic_state_free)(struct drm_atomic_state *state); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">fb_create</code></dt> <dd>Create a new framebuffer object. The core does basic checks on the requested metadata, but most of that is left to the driver. See <code class="xref c c-type docutils literal">struct drm_mode_fb_cmd2</code> for details. If the parameters are deemed valid and the backing storage objects in the underlying memory manager all exist, then the driver allocates a new <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a> structure, subclassed to contain driver-specific information (like the internal native buffer object references). It also needs to fill out all relevant metadata, which should be done by calling <a class="reference internal" href="drm-kms-helpers.html#c.drm_helper_mode_fill_fb_struct" title="drm_helper_mode_fill_fb_struct"><code class="xref c c-func docutils literal">drm_helper_mode_fill_fb_struct()</code></a>. The initialization is finalized by calling <a class="reference internal" href="#c.drm_framebuffer_init" title="drm_framebuffer_init"><code class="xref c c-func docutils literal">drm_framebuffer_init()</code></a>, which registers the framebuffer and makes it accessible to other threads. RETURNS: A new framebuffer with an initial reference count of 1 or a negative error code encoded with <code class="xref c c-func docutils literal">ERR_PTR()</code>. </dd> <dt><code class="docutils literal">get_format_info</code></dt> <dd>Allows a driver to return custom format information for special fb layouts (eg. ones with auxiliary compression control planes). RETURNS: The format information specific to the given fb metadata, or NULL if none is found. </dd> <dt><code class="docutils literal">output_poll_changed</code></dt> <dd>Callback used by helpers to inform the driver of output configuration changes. Drivers implementing fbdev emulation with the helpers can call drm_fb_helper_hotplug_changed from this hook to inform the fbdev helper of output changes. FIXME: Except that there’s no vtable for device-level helper callbacks there’s no reason this is a core function. </dd> <dt><code class="docutils literal">atomic_check</code></dt> <dd>This is the only hook to validate an atomic modeset update. This function must reject any modeset and state changes which the hardware or driver doesn’t support. This includes but is of course not limited to: <blockquote> <div><ul class="simple"> <li>Checking that the modes, framebuffers, scaling and placement requirements and so on are within the limits of the hardware.</li> <li>Checking that any hidden shared resources are not oversubscribed. This can be shared PLLs, shared lanes, overall memory bandwidth, display fifo space (where shared between planes or maybe even CRTCs).</li> <li>Checking that virtualized resources exported to userspace are not oversubscribed. For various reasons it can make sense to expose more planes, crtcs or encoders than which are physically there. One example is dual-pipe operations (which generally should be hidden from userspace if when lockstepped in hardware, exposed otherwise), where a plane might need 1 hardware plane (if it’s just on one pipe), 2 hardware planes (when it spans both pipes) or maybe even shared a hardware plane with a 2nd plane (if there’s a compatible plane requested on the area handled by the other pipe).</li> <li>Check that any transitional state is possible and that if requested, the update can indeed be done in the vblank period without temporarily disabling some functions.</li> <li>Check any other constraints the driver or hardware might have.</li> <li>This callback also needs to correctly fill out the <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state</code></a> in this update to make sure that <a class="reference internal" href="#c.drm_atomic_crtc_needs_modeset" title="drm_atomic_crtc_needs_modeset"><code class="xref c c-func docutils literal">drm_atomic_crtc_needs_modeset()</code></a> reflects the nature of the possible update and returns true if and only if the update cannot be applied without tearing within one vblank on that CRTC. The core uses that information to reject updates which require a full modeset (i.e. blanking the screen, or at least pausing updates for a substantial amount of time) if userspace has disallowed that in its request.</li> <li>The driver also does not need to repeat basic input validation like done for the corresponding legacy entry points. The core does that before calling this hook.</li> </ul> </div></blockquote> See the documentation of atomic_commit for an exhaustive list of error conditions which don’t have to be checked at the in this callback. See the documentation for <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> for how exactly an atomic modeset update is described. Drivers using the atomic helpers can implement this hook using <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_check" title="drm_atomic_helper_check"><code class="xref c c-func docutils literal">drm_atomic_helper_check()</code></a>, or one of the exported sub-functions of it. RETURNS: 0 on success or one of the below negative error codes: <blockquote class="last"> <div><ul class="simple"> <li>-EINVAL, if any of the above constraints are violated.</li> <li>-EDEADLK, when returned from an attempt to acquire an additional <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">drm_modeset_lock</code></a> through <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a>.</li> <li>-ENOMEM, if allocating additional state sub-structures failed due to lack of memory.</li> <li>-EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted. This can either be due to a pending signal, or because the driver needs to completely bail out to recover from an exceptional situation like a GPU hang. From a userspace point all errors are treated equally.</li> </ul> </div></blockquote> </dd> <dt><code class="docutils literal">atomic_commit</code></dt> <dd>This is the only hook to commit an atomic modeset update. The core guarantees that atomic_check has been called successfully before calling this function, and that nothing has been changed in the interim. See the documentation for <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> for how exactly an atomic modeset update is described. Drivers using the atomic helpers can implement this hook using <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_commit" title="drm_atomic_helper_commit"><code class="xref c c-func docutils literal">drm_atomic_helper_commit()</code></a>, or one of the exported sub-functions of it. Nonblocking commits (as indicated with the nonblock parameter) must do any preparatory work which might result in an unsuccessful commit in the context of this callback. The only exceptions are hardware errors resulting in -EIO. But even in that case the driver must ensure that the display pipe is at least running, to avoid compositors crashing when pageflips don’t work. Anything else, specifically committing the update to the hardware, should be done without blocking the caller. For updates which do not require a modeset this must be guaranteed. The driver must wait for any pending rendering to the new framebuffers to complete before executing the flip. It should also wait for any pending rendering from other drivers if the underlying buffer is a shared dma-buf. Nonblocking commits must not wait for rendering in the context of this callback. An application can request to be notified when the atomic commit has completed. These events are per-CRTC and can be distinguished by the CRTC index supplied in <code class="xref c c-type docutils literal">drm_event</code> to userspace. The drm core will supply a <code class="xref c c-type docutils literal">struct drm_event</code> in each CRTC’s <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.event</code></a>. See the documentation for <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.event</code></a> for more details about the precise semantics of this event. NOTE: Drivers are not allowed to shut down any display pipe successfully enabled through an atomic commit on their own. Doing so can result in compositors crashing if a page flip is suddenly rejected because the pipe is off. RETURNS: 0 on success or one of the below negative error codes: <blockquote> <div><ul class="simple"> <li>-EBUSY, if a nonblocking updated is requested and there is an earlier updated pending. Drivers are allowed to support a queue of outstanding updates, but currently no driver supports that. Note that drivers must wait for preceding updates to complete if a synchronous update is requested, they are not allowed to fail the commit in that case.</li> <li>-ENOMEM, if the driver failed to allocate memory. Specifically this can happen when trying to pin framebuffers, which must only be done when committing the state.</li> <li>-ENOSPC, as a refinement of the more generic -ENOMEM to indicate that the driver has run out of vram, iommu space or similar GPU address space needed for framebuffer.</li> <li>-EIO, if the hardware completely died.</li> <li>-EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted. This can either be due to a pending signal, or because the driver needs to completely bail out to recover from an exceptional situation like a GPU hang. From a userspace point of view all errors are treated equally.</li> </ul> </div></blockquote> This list is exhaustive. Specifically this hook is not allowed to return -EINVAL (any invalid requests should be caught in atomic_check) or -EDEADLK (this function must not acquire additional modeset locks). </dd> <dt><code class="docutils literal">atomic_state_alloc</code></dt> <dd>This optional hook can be used by drivers that want to subclass struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> to be able to track their own driver-private global state easily. If this hook is implemented, drivers must also implement atomic_state_clear and atomic_state_free. Subclassing of <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> is deprecated in favour of using <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> and <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">drm_private_obj</code></a>. RETURNS: A new <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> on success or NULL on failure. </dd> <dt><code class="docutils literal">atomic_state_clear</code></dt> <dd>This hook must clear any driver private state duplicated into the passed-in <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a>. This hook is called when the caller encountered a <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">drm_modeset_lock</code></a> deadlock and needs to drop all already acquired locks as part of the deadlock avoidance dance implemented in <a class="reference internal" href="#c.drm_modeset_backoff" title="drm_modeset_backoff"><code class="xref c c-func docutils literal">drm_modeset_backoff()</code></a>. Any duplicated state must be invalidated since a concurrent atomic update might change it, and the drm atomic interfaces always apply updates as relative changes to the current state. Drivers that implement this must call <a class="reference internal" href="#c.drm_atomic_state_default_clear" title="drm_atomic_state_default_clear"><code class="xref c c-func docutils literal">drm_atomic_state_default_clear()</code></a> to clear common state. Subclassing of <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> is deprecated in favour of using <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> and <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">drm_private_obj</code></a>. </dd> <dt><code class="docutils literal">atomic_state_free</code></dt> <dd>This hook needs driver private resources and the <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> itself. Note that the core first calls <a class="reference internal" href="#c.drm_atomic_state_clear" title="drm_atomic_state_clear"><code class="xref c c-func docutils literal">drm_atomic_state_clear()</code></a> to avoid code duplicate between the clear and free hooks. Drivers that implement this must call <a class="reference internal" href="#c.drm_atomic_state_default_release" title="drm_atomic_state_default_release"><code class="xref c c-func docutils literal">drm_atomic_state_default_release()</code></a> to release common resources. Subclassing of <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> is deprecated in favour of using <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> and <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">drm_private_obj</code></a>. </dd> </dl> Description Some global (i.e. not per-CRTC, connector, etc) mode setting functions that involve drivers. <dl class="type"> <dt id="c.drm_mode_config"> struct <code class="descname">drm_mode_config</code><a class="headerlink" href="#c.drm_mode_config" title="Permalink to this definition">¶</a></dt> <dd>Mode configuration control structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_mode_config { struct mutex mutex; struct drm_modeset_lock connection_mutex; struct drm_modeset_acquire_ctx *acquire_ctx; struct mutex idr_mutex; struct idr crtc_idr; struct idr tile_idr; struct mutex fb_lock; int num_fb; struct list_head fb_list; spinlock_t connector_list_lock; int num_connector; struct ida connector_ida; struct list_head connector_list; struct llist_head connector_free_list; struct work_struct connector_free_work; int num_encoder; struct list_head encoder_list; int num_total_plane; struct list_head plane_list; int num_crtc; struct list_head crtc_list; struct list_head property_list; int min_width, min_height; int max_width, max_height; const struct drm_mode_config_funcs *funcs; resource_size_t fb_base; bool poll_enabled; bool poll_running; bool delayed_event; struct delayed_work output_poll_work; struct mutex blob_lock; struct list_head property_blob_list; struct drm_property *edid_property; struct drm_property *dpms_property; struct drm_property *path_property; struct drm_property *tile_property; struct drm_property *link_status_property; struct drm_property *plane_type_property; struct drm_property *prop_src_x; struct drm_property *prop_src_y; struct drm_property *prop_src_w; struct drm_property *prop_src_h; struct drm_property *prop_crtc_x; struct drm_property *prop_crtc_y; struct drm_property *prop_crtc_w; struct drm_property *prop_crtc_h; struct drm_property *prop_fb_id; struct drm_property *prop_in_fence_fd; struct drm_property *prop_out_fence_ptr; struct drm_property *prop_crtc_id; struct drm_property *prop_active; struct drm_property *prop_mode_id; struct drm_property *dvi_i_subconnector_property; struct drm_property *dvi_i_select_subconnector_property; struct drm_property *tv_subconnector_property; struct drm_property *tv_select_subconnector_property; struct drm_property *tv_mode_property; struct drm_property *tv_left_margin_property; struct drm_property *tv_right_margin_property; struct drm_property *tv_top_margin_property; struct drm_property *tv_bottom_margin_property; struct drm_property *tv_brightness_property; struct drm_property *tv_contrast_property; struct drm_property *tv_flicker_reduction_property; struct drm_property *tv_overscan_property; struct drm_property *tv_saturation_property; struct drm_property *tv_hue_property; struct drm_property *scaling_mode_property; struct drm_property *aspect_ratio_property; struct drm_property *degamma_lut_property; struct drm_property *degamma_lut_size_property; struct drm_property *ctm_property; struct drm_property *gamma_lut_property; struct drm_property *gamma_lut_size_property; struct drm_property *suggested_x_property; struct drm_property *suggested_y_property; struct drm_property *non_desktop_property; struct drm_property *panel_orientation_property; uint32_t preferred_depth, prefer_shadow; bool async_page_flip; bool allow_fb_modifiers; struct drm_property *modifiers_property; uint32_t cursor_width, cursor_height; struct drm_atomic_state *suspend_state; const struct drm_mode_config_helper_funcs *helper_private; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">mutex</code></dt> <dd>This is the big scary modeset BKL which protects everything that isn’t protect otherwise. Scope is unclear and fuzzy, try to remove anything from under it’s protection and move it into more well-scoped locks. The one important thing this protects is the use of acquire_ctx. </dd> <dt><code class="docutils literal">connection_mutex</code></dt> <dd>This protects connector state and the connector to encoder to CRTC routing chain. For atomic drivers specifically this protects <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.state</code></a>. </dd> <dt><code class="docutils literal">acquire_ctx</code></dt> <dd>Global implicit acquire context used by atomic drivers for legacy IOCTLs. Deprecated, since implicit locking contexts make it impossible to use driver-private <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">struct drm_modeset_lock</code></a>. Users of this must hold mutex.</dd> <dt><code class="docutils literal">idr_mutex</code></dt> <dd>Mutex for KMS ID allocation and management. Protects both crtc_idr and tile_idr.</dd> <dt><code class="docutils literal">crtc_idr</code></dt> <dd>Main KMS ID tracking object. Use this idr for all IDs, fb, crtc, connector, modes - just makes life easier to have only one.</dd> <dt><code class="docutils literal">tile_idr</code></dt> <dd>Use this idr for allocating new IDs for tiled sinks like use in some high-res DP MST screens.</dd> <dt><code class="docutils literal">fb_lock</code></dt> <dd>Mutex to protect fb the global fb_list and num_fb.</dd> <dt><code class="docutils literal">num_fb</code></dt> <dd>Number of entries on fb_list.</dd> <dt><code class="docutils literal">fb_list</code></dt> <dd>List of all <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">struct drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">connector_list_lock</code></dt> <dd>Protects num_connector and connector_list and connector_free_list.</dd> <dt><code class="docutils literal">num_connector</code></dt> <dd>Number of connectors on this device. Protected by connector_list_lock.</dd> <dt><code class="docutils literal">connector_ida</code></dt> <dd>ID allocator for connector indices.</dd> <dt><code class="docutils literal">connector_list</code></dt> <dd>List of connector objects linked with <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.head</code></a>. Protected by connector_list_lock. Only use <a class="reference internal" href="#c.drm_for_each_connector_iter" title="drm_for_each_connector_iter"><code class="xref c c-func docutils literal">drm_for_each_connector_iter()</code></a> and <a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter"><code class="xref c c-type docutils literal">struct drm_connector_list_iter</code></a> to walk this list.</dd> <dt><code class="docutils literal">connector_free_list</code></dt> <dd>List of connector objects linked with <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.free_head</code></a>. Protected by connector_list_lock. Used by <a class="reference internal" href="#c.drm_for_each_connector_iter" title="drm_for_each_connector_iter"><code class="xref c c-func docutils literal">drm_for_each_connector_iter()</code></a> and <a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter"><code class="xref c c-type docutils literal">struct drm_connector_list_iter</code></a> to savely free connectors using connector_free_work.</dd> <dt><code class="docutils literal">connector_free_work</code></dt> <dd>Work to clean up connector_free_list.</dd> <dt><code class="docutils literal">num_encoder</code></dt> <dd>Number of encoders on this device. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">encoder_list</code></dt> <dd>List of encoder objects linked with <a class="reference internal" href="#c.drm_encoder" title="drm_encoder"><code class="xref c c-type docutils literal">drm_encoder.head</code></a>. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">num_total_plane</code></dt> <dd>Number of universal (i.e. with primary/curso) planes on this device. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">plane_list</code></dt> <dd>List of plane objects linked with <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane.head</code></a>. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">num_crtc</code></dt> <dd>Number of CRTCs on this device linked with <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.head</code></a>. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">crtc_list</code></dt> <dd>List of CRTC objects linked with <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.head</code></a>. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">property_list</code></dt> <dd>List of property type objects linked with <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property.head</code></a>. This is invariant over the lifetime of a device and hence doesn’t need any locks.</dd> <dt><code class="docutils literal">min_width</code></dt> <dd>minimum pixel width on this device</dd> <dt><code class="docutils literal">min_height</code></dt> <dd>minimum pixel height on this device</dd> <dt><code class="docutils literal">max_width</code></dt> <dd>maximum pixel width on this device</dd> <dt><code class="docutils literal">max_height</code></dt> <dd>maximum pixel height on this device</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>core driver provided mode setting functions</dd> <dt><code class="docutils literal">fb_base</code></dt> <dd>base address of the framebuffer</dd> <dt><code class="docutils literal">poll_enabled</code></dt> <dd>track polling support for this device</dd> <dt><code class="docutils literal">poll_running</code></dt> <dd>track polling status for this device</dd> <dt><code class="docutils literal">delayed_event</code></dt> <dd>track delayed poll uevent deliver for this device</dd> <dt><code class="docutils literal">output_poll_work</code></dt> <dd>delayed work for polling in process context</dd> <dt><code class="docutils literal">blob_lock</code></dt> <dd>Mutex for blob property allocation and management, protects property_blob_list and <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file"><code class="xref c c-type docutils literal">drm_file.blobs</code></a>.</dd> <dt><code class="docutils literal">property_blob_list</code></dt> <dd>List of all the blob property objects linked with <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob"><code class="xref c c-type docutils literal">drm_property_blob.head</code></a>. Protected by blob_lock.</dd> <dt><code class="docutils literal">edid_property</code></dt> <dd>Default connector property to hold the EDID of the currently connected sink, if any.</dd> <dt><code class="docutils literal">dpms_property</code></dt> <dd>Default connector property to control the connector’s DPMS state.</dd> <dt><code class="docutils literal">path_property</code></dt> <dd>Default connector property to hold the DP MST path for the port.</dd> <dt><code class="docutils literal">tile_property</code></dt> <dd>Default connector property to store the tile position of a tiled screen, for sinks which need to be driven with multiple CRTCs.</dd> <dt><code class="docutils literal">link_status_property</code></dt> <dd>Default connector property for link status of a connector</dd> <dt><code class="docutils literal">plane_type_property</code></dt> <dd>Default plane property to differentiate CURSOR, PRIMARY and OVERLAY legacy uses of planes.</dd> <dt><code class="docutils literal">prop_src_x</code></dt> <dd>Default atomic plane property for the plane source position in the connected <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">prop_src_y</code></dt> <dd>Default atomic plane property for the plane source position in the connected <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">prop_src_w</code></dt> <dd>Default atomic plane property for the plane source position in the connected <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">prop_src_h</code></dt> <dd>Default atomic plane property for the plane source position in the connected <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">prop_crtc_x</code></dt> <dd>Default atomic plane property for the plane destination position in the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> is is being shown on.</dd> <dt><code class="docutils literal">prop_crtc_y</code></dt> <dd>Default atomic plane property for the plane destination position in the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> is is being shown on.</dd> <dt><code class="docutils literal">prop_crtc_w</code></dt> <dd>Default atomic plane property for the plane destination position in the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> is is being shown on.</dd> <dt><code class="docutils literal">prop_crtc_h</code></dt> <dd>Default atomic plane property for the plane destination position in the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> is is being shown on.</dd> <dt><code class="docutils literal">prop_fb_id</code></dt> <dd>Default atomic plane property to specify the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>.</dd> <dt><code class="docutils literal">prop_in_fence_fd</code></dt> <dd>Sync File fd representing the incoming fences for a Plane.</dd> <dt><code class="docutils literal">prop_out_fence_ptr</code></dt> <dd>Sync File fd pointer representing the outgoing fences for a CRTC. Userspace should provide a pointer to a value of type s32, and then cast that pointer to u64.</dd> <dt><code class="docutils literal">prop_crtc_id</code></dt> <dd>Default atomic plane property to specify the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>.</dd> <dt><code class="docutils literal">prop_active</code></dt> <dd>Default atomic CRTC property to control the active state, which is the simplified implementation for DPMS in atomic drivers.</dd> <dt><code class="docutils literal">prop_mode_id</code></dt> <dd>Default atomic CRTC property to set the mode for a CRTC. A 0 mode implies that the CRTC is entirely disabled - all connectors must be of and active must be set to disabled, too.</dd> <dt><code class="docutils literal">dvi_i_subconnector_property</code></dt> <dd>Optional DVI-I property to differentiate between analog or digital mode.</dd> <dt><code class="docutils literal">dvi_i_select_subconnector_property</code></dt> <dd>Optional DVI-I property to select between analog or digital mode.</dd> <dt><code class="docutils literal">tv_subconnector_property</code></dt> <dd>Optional TV property to differentiate between different TV connector types.</dd> <dt><code class="docutils literal">tv_select_subconnector_property</code></dt> <dd>Optional TV property to select between different TV connector types.</dd> <dt><code class="docutils literal">tv_mode_property</code></dt> <dd>Optional TV property to select the output TV mode.</dd> <dt><code class="docutils literal">tv_left_margin_property</code></dt> <dd>Optional TV property to set the left margin.</dd> <dt><code class="docutils literal">tv_right_margin_property</code></dt> <dd>Optional TV property to set the right margin.</dd> <dt><code class="docutils literal">tv_top_margin_property</code></dt> <dd>Optional TV property to set the right margin.</dd> <dt><code class="docutils literal">tv_bottom_margin_property</code></dt> <dd>Optional TV property to set the right margin.</dd> <dt><code class="docutils literal">tv_brightness_property</code></dt> <dd>Optional TV property to set the brightness.</dd> <dt><code class="docutils literal">tv_contrast_property</code></dt> <dd>Optional TV property to set the contrast.</dd> <dt><code class="docutils literal">tv_flicker_reduction_property</code></dt> <dd>Optional TV property to control the flicker reduction mode.</dd> <dt><code class="docutils literal">tv_overscan_property</code></dt> <dd>Optional TV property to control the overscan setting.</dd> <dt><code class="docutils literal">tv_saturation_property</code></dt> <dd>Optional TV property to set the saturation.</dd> <dt><code class="docutils literal">tv_hue_property</code></dt> <dd>Optional TV property to set the hue.</dd> <dt><code class="docutils literal">scaling_mode_property</code></dt> <dd>Optional connector property to control the upscaling, mostly used for built-in panels.</dd> <dt><code class="docutils literal">aspect_ratio_property</code></dt> <dd>Optional connector property to control the HDMI infoframe aspect ratio setting.</dd> <dt><code class="docutils literal">degamma_lut_property</code></dt> <dd>Optional CRTC property to set the LUT used to convert the framebuffer’s colors to linear gamma.</dd> <dt><code class="docutils literal">degamma_lut_size_property</code></dt> <dd>Optional CRTC property for the size of the degamma LUT as supported by the driver (read-only).</dd> <dt><code class="docutils literal">ctm_property</code></dt> <dd>Optional CRTC property to set the matrix used to convert colors after the lookup in the degamma LUT.</dd> <dt><code class="docutils literal">gamma_lut_property</code></dt> <dd>Optional CRTC property to set the LUT used to convert the colors, after the CTM matrix, to the gamma space of the connected screen.</dd> <dt><code class="docutils literal">gamma_lut_size_property</code></dt> <dd>Optional CRTC property for the size of the gamma LUT as supported by the driver (read-only).</dd> <dt><code class="docutils literal">suggested_x_property</code></dt> <dd>Optional connector property with a hint for the position of the output on the host’s screen.</dd> <dt><code class="docutils literal">suggested_y_property</code></dt> <dd>Optional connector property with a hint for the position of the output on the host’s screen.</dd> <dt><code class="docutils literal">non_desktop_property</code></dt> <dd>Optional connector property with a hint that device isn’t a standard display, and the console/desktop, should not be displayed on it.</dd> <dt><code class="docutils literal">panel_orientation_property</code></dt> <dd>Optional connector property indicating how the lcd-panel is mounted inside the casing (e.g. normal or upside-down).</dd> <dt><code class="docutils literal">preferred_depth</code></dt> <dd>preferred RBG pixel depth, used by fb helpers</dd> <dt><code class="docutils literal">prefer_shadow</code></dt> <dd>hint to userspace to prefer shadow-fb rendering</dd> <dt><code class="docutils literal">async_page_flip</code></dt> <dd>Does this device support async flips on the primary plane?</dd> <dt><code class="docutils literal">allow_fb_modifiers</code></dt> <dd>Whether the driver supports fb modifiers in the ADDFB2.1 ioctl call.</dd> <dt><code class="docutils literal">modifiers_property</code></dt> <dd>Plane property to list support modifier/format combination.</dd> <dt><code class="docutils literal">cursor_width</code></dt> <dd>hint to userspace for max cursor width</dd> <dt><code class="docutils literal">cursor_height</code></dt> <dd>hint to userspace for max cursor height</dd> <dt><code class="docutils literal">suspend_state</code></dt> <dd>Atomic state when suspended. Set by <a class="reference internal" href="drm-kms-helpers.html#c.drm_mode_config_helper_suspend" title="drm_mode_config_helper_suspend"><code class="xref c c-func docutils literal">drm_mode_config_helper_suspend()</code></a> and cleared by <a class="reference internal" href="drm-kms-helpers.html#c.drm_mode_config_helper_resume" title="drm_mode_config_helper_resume"><code class="xref c c-func docutils literal">drm_mode_config_helper_resume()</code></a>.</dd> <dt><code class="docutils literal">helper_private</code></dt> <dd>mid-layer private data</dd> </dl> Description Core mode resource tracking structure. All CRTC, encoders, and connectors enumerated by the driver are added here, as are global properties. Some global restrictions are also here, e.g. dimension restrictions. <dl class="function"> <dt id="c.drm_mode_config_reset"> void <code class="descname">drm_mode_config_reset</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_config_reset" title="Permalink to this definition">¶</a></dt> <dd>call ->reset callbacks </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> </dl> Description This functions calls all the crtc’s, encoder’s and connector’s ->reset callback. Drivers can use this in e.g. their driver load or resume code to reset hardware and software state. <dl class="function"> <dt id="c.drm_mode_config_init"> void <code class="descname">drm_mode_config_init</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_config_init" title="Permalink to this definition">¶</a></dt> <dd>initialize DRM mode_configuration structure </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Initialize dev‘s mode_config structure, used for tracking the graphics configuration of dev. Since this initializes the modeset locks, no locking is possible. Which is no problem, since this should happen single threaded at init time. It is the driver’s problem to ensure this guarantee. <dl class="function"> <dt id="c.drm_mode_config_cleanup"> void <code class="descname">drm_mode_config_cleanup</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_config_cleanup" title="Permalink to this definition">¶</a></dt> <dd>free up DRM mode_config info </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Free up all the connectors and CRTCs associated with this DRM device, then free up the framebuffers and associated buffer objects. Note that since this /should/ happen single-threaded at driver/device teardown time, no locking is required. It’s the driver’s job to ensure that this guarantee actually holds true. FIXME: cleanup any dangling user buffer objects too </div> <div class="section" id="modeset-base-object-abstraction"> <h2>Modeset Base Object Abstraction<a class="headerlink" href="#modeset-base-object-abstraction" title="Permalink to this headline">¶</a></h2> <div class="figure" id="id7"> <img alt="Mode Objects and Properties" src="../_images/DOT-1eee3f74bb2de20b2b68c4aa6c9c1cabe5078857.svg" />Mode Objects and Properties </div> The base structure for all KMS objects is <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object"><code class="xref c c-type docutils literal">struct drm_mode_object</code></a>. One of the base services it provides is tracking properties, which are especially important for the atomic IOCTL (see <a class="reference internal" href="#atomic-mode-setting">Atomic Mode Setting</a>). The somewhat surprising part here is that properties are not directly instantiated on each object, but free-standing mode objects themselves, represented by <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">struct drm_property</code></a>, which only specify the type and value range of a property. Any given property can be attached multiple times to different objects using <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. <dl class="type"> <dt id="c.drm_mode_object"> struct <code class="descname">drm_mode_object</code><a class="headerlink" href="#c.drm_mode_object" title="Permalink to this definition">¶</a></dt> <dd>base structure for modeset objects </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_mode_object { uint32_t id; uint32_t type; struct drm_object_properties *properties; struct kref refcount; void (*free_cb)(struct kref *kref); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">id</code></dt> <dd>userspace visible identifier</dd> <dt><code class="docutils literal">type</code></dt> <dd>type of the object, one of DRM_MODE_OBJECT_*</dd> <dt><code class="docutils literal">properties</code></dt> <dd>properties attached to this object, including values</dd> <dt><code class="docutils literal">refcount</code></dt> <dd>reference count for objects which with dynamic lifetime</dd> <dt><code class="docutils literal">free_cb</code></dt> <dd>free function callback, only set for objects with dynamic lifetime</dd> </dl> Description Base structure for modeset objects visible to userspace. Objects can be looked up using <a class="reference internal" href="#c.drm_mode_object_find" title="drm_mode_object_find"><code class="xref c c-func docutils literal">drm_mode_object_find()</code></a>. Besides basic uapi interface properties like id and type it provides two services: <ul class="simple"> <li>It tracks attached properties and their values. This is used by <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>, <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> and <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a>. Properties are attached by calling <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a> before the object is visible to userspace.</li> <li>For objects with dynamic lifetimes (as indicated by a non-NULL free_cb) it provides reference counting through <a class="reference internal" href="#c.drm_mode_object_get" title="drm_mode_object_get"><code class="xref c c-func docutils literal">drm_mode_object_get()</code></a> and <a class="reference internal" href="#c.drm_mode_object_put" title="drm_mode_object_put"><code class="xref c c-func docutils literal">drm_mode_object_put()</code></a>. This is used by <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>, <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a> and <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob"><code class="xref c c-type docutils literal">drm_property_blob</code></a>. These objects provide specialized reference counting wrappers.</li> </ul> <dl class="type"> <dt id="c.drm_object_properties"> struct <code class="descname">drm_object_properties</code><a class="headerlink" href="#c.drm_object_properties" title="Permalink to this definition">¶</a></dt> <dd>property tracking for <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object"><code class="xref c c-type docutils literal">drm_mode_object</code></a> </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_object_properties { int count; struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY]; uint64_t values[DRM_OBJECT_MAX_PROPERTY]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">count</code></dt> <dd>number of valid properties, must be less than or equal to DRM_OBJECT_MAX_PROPERTY.</dd> <dt><code class="docutils literal">properties</code></dt> <dd>Array of pointers to <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a>. NOTE: if we ever start dynamically destroying properties (ie. not at <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a> time), then we’d have to do a better job of detaching property from mode objects to avoid dangling property pointers: </dd> <dt><code class="docutils literal">values</code></dt> <dd>Array to store the property values, matching properties. Do not read/write values directly, but use <a class="reference internal" href="#c.drm_object_property_get_value" title="drm_object_property_get_value"><code class="xref c c-func docutils literal">drm_object_property_get_value()</code></a> and <a class="reference internal" href="#c.drm_object_property_set_value" title="drm_object_property_set_value"><code class="xref c c-func docutils literal">drm_object_property_set_value()</code></a>. Note that atomic drivers do not store mutable properties in this array, but only the decoded values in the corresponding state structure. The decoding is done using the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.atomic_get_property</code></a> and <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.atomic_set_property</code></a> hooks for <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>. For <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> the hooks are <a class="reference internal" href="#c.drm_plane_funcs" title="drm_plane_funcs"><code class="xref c c-type docutils literal">drm_plane_funcs.atomic_get_property</code></a> and <a class="reference internal" href="#c.drm_plane_funcs" title="drm_plane_funcs"><code class="xref c c-type docutils literal">drm_plane_funcs.atomic_set_property</code></a>. And for <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> the hooks are <a class="reference internal" href="#c.drm_connector_funcs" title="drm_connector_funcs"><code class="xref c c-type docutils literal">drm_connector_funcs.atomic_get_property</code></a> and <a class="reference internal" href="#c.drm_connector_funcs" title="drm_connector_funcs"><code class="xref c c-type docutils literal">drm_connector_funcs.atomic_set_property</code></a> . Hence atomic drivers should not use <a class="reference internal" href="#c.drm_object_property_set_value" title="drm_object_property_set_value"><code class="xref c c-func docutils literal">drm_object_property_set_value()</code></a> and <a class="reference internal" href="#c.drm_object_property_get_value" title="drm_object_property_get_value"><code class="xref c c-func docutils literal">drm_object_property_get_value()</code></a> on mutable objects, i.e. those without the DRM_MODE_PROP_IMMUTABLE flag set. </dd> </dl> <dl class="function"> <dt id="c.drm_mode_object_reference"> void <code class="descname">drm_mode_object_reference</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj)<a class="headerlink" href="#c.drm_mode_object_reference" title="Permalink to this definition">¶</a></dt> <dd>acquire a mode object reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>DRM mode object</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_mode_object_get" title="drm_mode_object_get"><code class="xref c c-func docutils literal">drm_mode_object_get()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_mode_object_unreference"> void <code class="descname">drm_mode_object_unreference</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj)<a class="headerlink" href="#c.drm_mode_object_unreference" title="Permalink to this definition">¶</a></dt> <dd>release a mode object reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>DRM mode object</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_mode_object_put" title="drm_mode_object_put"><code class="xref c c-func docutils literal">drm_mode_object_put()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_mode_object_find"> struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * <code class="descname">drm_mode_object_find</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id, uint32_t type)<a class="headerlink" href="#c.drm_mode_object_find" title="Permalink to this definition">¶</a></dt> <dd>look up a drm object with static lifetime </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>id of the mode object</dd> <dt><code class="docutils literal">uint32_t type</code></dt> <dd>type of the mode object</dd> </dl> Description This function is used to look up a modeset object. It will acquire a reference for reference counted objects. This reference must be dropped again by callind <a class="reference internal" href="#c.drm_mode_object_put" title="drm_mode_object_put"><code class="xref c c-func docutils literal">drm_mode_object_put()</code></a>. <dl class="function"> <dt id="c.drm_mode_object_put"> void <code class="descname">drm_mode_object_put</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj)<a class="headerlink" href="#c.drm_mode_object_put" title="Permalink to this definition">¶</a></dt> <dd>release a mode object reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>DRM mode object</dd> </dl> Description This function decrements the object’s refcount if it is a refcounted modeset object. It is a no-op on any other object. This is used to drop references acquired with <a class="reference internal" href="#c.drm_mode_object_get" title="drm_mode_object_get"><code class="xref c c-func docutils literal">drm_mode_object_get()</code></a>. <dl class="function"> <dt id="c.drm_mode_object_get"> void <code class="descname">drm_mode_object_get</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj)<a class="headerlink" href="#c.drm_mode_object_get" title="Permalink to this definition">¶</a></dt> <dd>acquire a mode object reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>DRM mode object</dd> </dl> Description This function increments the object’s refcount if it is a refcounted modeset object. It is a no-op on any other object. References should be dropped again by calling <a class="reference internal" href="#c.drm_mode_object_put" title="drm_mode_object_put"><code class="xref c c-func docutils literal">drm_mode_object_put()</code></a>. <dl class="function"> <dt id="c.drm_object_attach_property"> void <code class="descname">drm_object_attach_property</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint64_t init_val)<a class="headerlink" href="#c.drm_object_attach_property" title="Permalink to this definition">¶</a></dt> <dd>attach a property to a modeset object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>drm modeset object</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to attach</dd> <dt><code class="docutils literal">uint64_t init_val</code></dt> <dd>initial value of the property</dd> </dl> Description This attaches the given property to the modeset object with the given initial value. Currently this function cannot fail since the properties are stored in a statically sized array. <dl class="function"> <dt id="c.drm_object_property_set_value"> int <code class="descname">drm_object_property_set_value</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint64_t val)<a class="headerlink" href="#c.drm_object_property_set_value" title="Permalink to this definition">¶</a></dt> <dd>set the value of a property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>drm mode object to set property value for</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to set</dd> <dt><code class="docutils literal">uint64_t val</code></dt> <dd>value the property should be set to</dd> </dl> Description This function sets a given property on a given object. This function only changes the software state of the property, it does not call into the driver’s ->set_property callback. Note that atomic drivers should not have any need to call this, the core will ensure consistency of values reported back to userspace through the appropriate ->atomic_get_property callback. Only legacy drivers should call this function to update the tracked value (after clamping and other restrictions have been applied). Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_object_property_get_value"> int <code class="descname">drm_object_property_get_value</code>(struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint64_t * val)<a class="headerlink" href="#c.drm_object_property_get_value" title="Permalink to this definition">¶</a></dt> <dd>retrieve the value of a property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_object * obj</code></dt> <dd>drm mode object to get property value from</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to retrieve</dd> <dt><code class="docutils literal">uint64_t * val</code></dt> <dd>storage for the property value</dd> </dl> Description This function retrieves the softare state of the given property for the given property. Since there is no driver callback to retrieve the current property value this might be out of sync with the hardware, depending upon the driver and property. Atomic drivers should never call this function directly, the core will read out property values through the various ->atomic_get_property callbacks. Return Zero on success, error code on failure. </div> <div class="section" id="atomic-mode-setting"> <h2>Atomic Mode Setting<a class="headerlink" href="#atomic-mode-setting" title="Permalink to this headline">¶</a></h2> <div class="figure" id="id8"> <img alt="Mode Objects and Properties" src="../_images/DOT-69c6997054dbfdfb0892fa0cab076cfd8074c7ed.svg" />Mode Objects and Properties </div> Atomic provides transactional modeset (including planes) updates, but a bit differently from the usual transactional approach of try-commit and rollback: <ul class="simple"> <li>Firstly, no hardware changes are allowed when the commit would fail. This allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows userspace to explore whether certain configurations would work or not.</li> <li>This would still allow setting and rollback of just the software state, simplifying conversion of existing drivers. But auditing drivers for correctness of the atomic_check code becomes really hard with that: Rolling back changes in data structures all over the place is hard to get right.</li> <li>Lastly, for backwards compatibility and to support all use-cases, atomic updates need to be incremental and be able to execute in parallel. Hardware doesn’t always allow it, but where possible plane updates on different CRTCs should not interfere, and not get stalled due to output routing changing on different CRTCs.</li> </ul> Taken all together there’s two consequences for the atomic design: <ul class="simple"> <li>The overall state is split up into per-object state structures: <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> for planes, <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> for CRTCs and <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> for connectors. These are the only objects with userspace-visible and settable state. For internal state drivers can subclass these structures through embeddeding, or add entirely new state structures for their globally shared hardware functions.</li> <li>An atomic update is assembled and validated as an entirely free-standing pile of structures within the <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> container. Driver private state structures are also tracked in the same structure; see the next chapter. Only when a state is committed is it applied to the driver and modeset objects. This way rolling back an update boils down to releasing memory and unreferencing objects like framebuffers.</li> </ul> Read on in this chapter, and also in <a class="reference internal" href="drm-kms-helpers.html#drm-atomic-helper">Atomic Modeset Helper Functions Reference</a> for more detailed coverage of specific topics. <div class="section" id="handling-driver-private-state"> <h3>Handling Driver Private State<a class="headerlink" href="#handling-driver-private-state" title="Permalink to this headline">¶</a></h3> Very often the DRM objects exposed to userspace in the atomic modeset api (<a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a>, <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> and <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a>) do not map neatly to the underlying hardware. Especially for any kind of shared resources (e.g. shared clocks, scaler units, bandwidth and fifo limits shared among a group of planes or CRTCs, and so on) it makes sense to model these as independent objects. Drivers then need to do similar state tracking and commit ordering for such private (since not exposed to userpace) objects as the atomic core and helpers already provide for connectors, planes and CRTCs. To make this easier on drivers the atomic core provides some support to track driver private state objects using struct <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">drm_private_obj</code></a>, with the associated state struct <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a>. Similar to userspace-exposed objects, private state structures can be acquired by calling <a class="reference internal" href="#c.drm_atomic_get_private_obj_state" title="drm_atomic_get_private_obj_state"><code class="xref c c-func docutils literal">drm_atomic_get_private_obj_state()</code></a>. Since this function does not take care of locking, drivers should wrap it for each type of private state object they have with the required call to <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a> for the corresponding <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">drm_modeset_lock</code></a>. All private state structures contained in a <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> update can be iterated using <a class="reference internal" href="#c.for_each_oldnew_private_obj_in_state" title="for_each_oldnew_private_obj_in_state"><code class="xref c c-func docutils literal">for_each_oldnew_private_obj_in_state()</code></a>, <a class="reference internal" href="#c.for_each_new_private_obj_in_state" title="for_each_new_private_obj_in_state"><code class="xref c c-func docutils literal">for_each_new_private_obj_in_state()</code></a> and <a class="reference internal" href="#c.for_each_old_private_obj_in_state" title="for_each_old_private_obj_in_state"><code class="xref c c-func docutils literal">for_each_old_private_obj_in_state()</code></a>. Drivers are recommended to wrap these for each type of driver private state object they have, filtering on <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">drm_private_obj.funcs</code></a> using <code class="xref c c-func docutils literal">for_each_if()</code>, at least if they want to iterate over all objects of a given type. An earlier way to handle driver private state was by subclassing struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a>. But since that encourages non-standard ways to implement the check/commit split atomic requires (by using e.g. “check and rollback or commit instead” of “duplicate state, check, then either commit or release duplicated state) it is deprecated in favour of using <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a>. </div> <div class="section" id="atomic-mode-setting-function-reference"> <h3>Atomic Mode Setting Function Reference<a class="headerlink" href="#atomic-mode-setting-function-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_crtc_commit"> struct <code class="descname">drm_crtc_commit</code><a class="headerlink" href="#c.drm_crtc_commit" title="Permalink to this definition">¶</a></dt> <dd>track modeset commits on a CRTC </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_crtc_commit { struct drm_crtc *crtc; struct kref ref; struct completion flip_done; struct completion hw_done; struct completion cleanup_done; struct list_head commit_entry; struct drm_pending_vblank_event *event; bool abort_completion; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">crtc</code></dt> <dd>DRM CRTC for this commit.</dd> <dt><code class="docutils literal">ref</code></dt> <dd>Reference count for this structure. Needed to allow blocking on completions without the risk of the completion disappearing meanwhile.</dd> <dt><code class="docutils literal">flip_done</code></dt> <dd>Will be signaled when the hardware has flipped to the new set of buffers. Signals at the same time as when the drm event for this commit is sent to userspace, or when an out-fence is singalled. Note that for most hardware, in most cases this happens after hw_done is signalled.</dd> <dt><code class="docutils literal">hw_done</code></dt> <dd>Will be signalled when all hw register changes for this commit have been written out. Especially when disabling a pipe this can be much later than than flip_done, since that can signal already when the screen goes black, whereas to fully shut down a pipe more register I/O is required. Note that this does not need to include separately reference-counted resources like backing storage buffer pinning, or runtime pm management. </dd> <dt><code class="docutils literal">cleanup_done</code></dt> <dd>Will be signalled after old buffers have been cleaned up by calling <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_cleanup_planes" title="drm_atomic_helper_cleanup_planes"><code class="xref c c-func docutils literal">drm_atomic_helper_cleanup_planes()</code></a>. Since this can only happen after a vblank wait completed it might be a bit later. This completion is useful to throttle updates and avoid hardware updates getting ahead of the buffer cleanup too much.</dd> <dt><code class="docutils literal">commit_entry</code></dt> <dd>Entry on the per-CRTC <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.commit_list</code></a>. Protected by $drm_crtc.commit_lock.</dd> <dt><code class="docutils literal">event</code></dt> <dd><a class="reference internal" href="#c.drm_pending_vblank_event" title="drm_pending_vblank_event"><code class="xref c c-type docutils literal">drm_pending_vblank_event</code></a> pointer to clean up private events.</dd> <dt><code class="docutils literal">abort_completion</code></dt> <dd>A flag that’s set after drm_atomic_helper_setup_commit takes a second reference for the completion of $drm_crtc_state.event. It’s used by the free code to remove the second reference if commit fails.</dd> </dl> Description This structure is used to track pending modeset changes and atomic commit on a per-CRTC basis. Since updating the list should never block this structure is reference counted to allow waiters to safely wait on an event to complete, without holding any locks. It has 3 different events in total to allow a fine-grained synchronization between outstanding updates: <div class="highlight-none"><div class="highlight"><pre>atomic commit thread hardware write new state into hardware ----> ... signal hw_done switch to new state on next ... v/hblank wait for buffers to show up ... ... send completion irq irq handler signals flip_done cleanup old buffers signal cleanup_done wait for flip_done <---- clean up atomic state </pre></div> </div> The important bit to know is that cleanup_done is the terminal event, but the ordering between flip_done and hw_done is entirely up to the specific driver and modeset state change. For an implementation of how to use this look at <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_setup_commit" title="drm_atomic_helper_setup_commit"><code class="xref c c-func docutils literal">drm_atomic_helper_setup_commit()</code></a> from the atomic helper library. <dl class="type"> <dt id="c.drm_private_state_funcs"> struct <code class="descname">drm_private_state_funcs</code><a class="headerlink" href="#c.drm_private_state_funcs" title="Permalink to this definition">¶</a></dt> <dd>atomic state functions for private objects </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_private_state_funcs { struct drm_private_state *(*atomic_duplicate_state)(struct drm_private_obj *obj); void (*atomic_destroy_state)(struct drm_private_obj *obj, struct drm_private_state *state); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">atomic_duplicate_state</code></dt> <dd>Duplicate the current state of the private object and return it. It is an error to call this before obj->state has been initialized. RETURNS: Duplicated atomic state or NULL when obj->state is not initialized or allocation failed. </dd> <dt><code class="docutils literal">atomic_destroy_state</code></dt> <dd>Frees the private object state created with atomic_duplicate_state.</dd> </dl> Description These hooks are used by atomic helpers to create, swap and destroy states of private objects. The structure itself is used as a vtable to identify the associated private object type. Each private object type that needs to be added to the atomic states is expected to have an implementation of these hooks and pass a pointer to it’s drm_private_state_funcs struct to <a class="reference internal" href="#c.drm_atomic_get_private_obj_state" title="drm_atomic_get_private_obj_state"><code class="xref c c-func docutils literal">drm_atomic_get_private_obj_state()</code></a>. <dl class="type"> <dt id="c.drm_private_obj"> struct <code class="descname">drm_private_obj</code><a class="headerlink" href="#c.drm_private_obj" title="Permalink to this definition">¶</a></dt> <dd>base struct for driver private atomic object </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_private_obj { struct drm_private_state *state; const struct drm_private_state_funcs *funcs; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">state</code></dt> <dd>Current atomic state for this driver private object.</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>Functions to manipulate the state of this driver private object, see <a class="reference internal" href="#c.drm_private_state_funcs" title="drm_private_state_funcs"><code class="xref c c-type docutils literal">drm_private_state_funcs</code></a>.</dd> </dl> Description A driver private object is initialized by calling <a class="reference internal" href="#c.drm_atomic_private_obj_init" title="drm_atomic_private_obj_init"><code class="xref c c-func docutils literal">drm_atomic_private_obj_init()</code></a> and cleaned up by calling <a class="reference internal" href="#c.drm_atomic_private_obj_fini" title="drm_atomic_private_obj_fini"><code class="xref c c-func docutils literal">drm_atomic_private_obj_fini()</code></a>. Currently only tracks the state update functions and the opaque driver private state itself, but in the future might also track which <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">drm_modeset_lock</code></a> is required to duplicate and update this object’s state. <dl class="type"> <dt id="c.drm_private_state"> struct <code class="descname">drm_private_state</code><a class="headerlink" href="#c.drm_private_state" title="Permalink to this definition">¶</a></dt> <dd>base struct for driver private object state </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_private_state { struct drm_atomic_state *state; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">state</code></dt> <dd>backpointer to global drm_atomic_state</dd> </dl> Description Currently only contains a backpointer to the overall atomic update, but in the future also might hold synchronization information similar to e.g. <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.commit</code></a>. <dl class="type"> <dt id="c.drm_atomic_state"> struct <code class="descname">drm_atomic_state</code><a class="headerlink" href="#c.drm_atomic_state" title="Permalink to this definition">¶</a></dt> <dd>the global state object for atomic updates </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_atomic_state { struct kref ref; struct drm_device *dev; bool allow_modeset : 1; bool legacy_cursor_update : 1; bool async_update : 1; struct __drm_planes_state *planes; struct __drm_crtcs_state *crtcs; int num_connector; struct __drm_connnectors_state *connectors; int num_private_objs; struct __drm_private_objs_state *private_objs; struct drm_modeset_acquire_ctx *acquire_ctx; struct drm_crtc_commit *fake_commit; struct work_struct commit_work; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">ref</code></dt> <dd>count of all references to this state (will not be freed until zero)</dd> <dt><code class="docutils literal">dev</code></dt> <dd>parent DRM device</dd> <dt><code class="docutils literal">allow_modeset</code></dt> <dd>allow full modeset</dd> <dt><code class="docutils literal">legacy_cursor_update</code></dt> <dd>hint to enforce legacy cursor IOCTL semantics</dd> <dt><code class="docutils literal">async_update</code></dt> <dd>hint for asynchronous plane update</dd> <dt><code class="docutils literal">planes</code></dt> <dd>pointer to array of structures with per-plane data</dd> <dt><code class="docutils literal">crtcs</code></dt> <dd>pointer to array of CRTC pointers</dd> <dt><code class="docutils literal">num_connector</code></dt> <dd>size of the connectors and connector_states arrays</dd> <dt><code class="docutils literal">connectors</code></dt> <dd>pointer to array of structures with per-connector data</dd> <dt><code class="docutils literal">num_private_objs</code></dt> <dd>size of the private_objs array</dd> <dt><code class="docutils literal">private_objs</code></dt> <dd>pointer to array of private object pointers</dd> <dt><code class="docutils literal">acquire_ctx</code></dt> <dd>acquire context for this atomic modeset state update</dd> <dt><code class="docutils literal">fake_commit</code></dt> <dd>Used for signaling unbound planes/connectors. When a connector or plane is not bound to any CRTC, it’s still important to preserve linearity to prevent the atomic states from being freed to early. This commit (if set) is not bound to any crtc, but will be completed when <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_commit_hw_done" title="drm_atomic_helper_commit_hw_done"><code class="xref c c-func docutils literal">drm_atomic_helper_commit_hw_done()</code></a> is called. </dd> <dt><code class="docutils literal">commit_work</code></dt> <dd>Work item which can be used by the driver or helpers to execute the commit without blocking.</dd> </dl> Description States are added to an atomic update by calling <a class="reference internal" href="#c.drm_atomic_get_crtc_state" title="drm_atomic_get_crtc_state"><code class="xref c c-func docutils literal">drm_atomic_get_crtc_state()</code></a>, <a class="reference internal" href="#c.drm_atomic_get_plane_state" title="drm_atomic_get_plane_state"><code class="xref c c-func docutils literal">drm_atomic_get_plane_state()</code></a>, <a class="reference internal" href="#c.drm_atomic_get_connector_state" title="drm_atomic_get_connector_state"><code class="xref c c-func docutils literal">drm_atomic_get_connector_state()</code></a>, or for private state structures, <a class="reference internal" href="#c.drm_atomic_get_private_obj_state" title="drm_atomic_get_private_obj_state"><code class="xref c c-func docutils literal">drm_atomic_get_private_obj_state()</code></a>. <dl class="function"> <dt id="c.drm_crtc_commit_get"> struct <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit">drm_crtc_commit</a> * <code class="descname">drm_crtc_commit_get</code>(struct <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit">drm_crtc_commit</a> * commit)<a class="headerlink" href="#c.drm_crtc_commit_get" title="Permalink to this definition">¶</a></dt> <dd>acquire a reference to the CRTC commit </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc_commit * commit</code></dt> <dd>CRTC commit</dd> </dl> Description Increases the reference of commit. Return The pointer to commit, with reference increased. <dl class="function"> <dt id="c.drm_crtc_commit_put"> void <code class="descname">drm_crtc_commit_put</code>(struct <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit">drm_crtc_commit</a> * commit)<a class="headerlink" href="#c.drm_crtc_commit_put" title="Permalink to this definition">¶</a></dt> <dd>release a reference to the CRTC commmit </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc_commit * commit</code></dt> <dd>CRTC commit</dd> </dl> Description This releases a reference to commit which is freed after removing the final reference. No locking required and callable from any context. <dl class="function"> <dt id="c.drm_atomic_state_get"> struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * <code class="descname">drm_atomic_state_get</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_get" title="Permalink to this definition">¶</a></dt> <dd>acquire a reference to the atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>The atomic state</dd> </dl> Description Returns a new reference to the state <dl class="function"> <dt id="c.drm_atomic_state_put"> void <code class="descname">drm_atomic_state_put</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_put" title="Permalink to this definition">¶</a></dt> <dd>release a reference to the atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>The atomic state</dd> </dl> Description This releases a reference to state which is freed after removing the final reference. No locking required and callable from any context. <dl class="function"> <dt id="c.drm_atomic_get_existing_crtc_state"> struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * <code class="descname">drm_atomic_get_existing_crtc_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_get_existing_crtc_state" title="Permalink to this definition">¶</a></dt> <dd>get crtc state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to grab</dd> </dl> Description This function returns the crtc state for the given crtc, or NULL if the crtc is not part of the global atomic state. This function is deprecated, drm_atomic_get_old_crtc_state or drm_atomic_get_new_crtc_state should be used instead. <dl class="function"> <dt id="c.drm_atomic_get_old_crtc_state"> struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * <code class="descname">drm_atomic_get_old_crtc_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_get_old_crtc_state" title="Permalink to this definition">¶</a></dt> <dd>get old crtc state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to grab</dd> </dl> Description This function returns the old crtc state for the given crtc, or NULL if the crtc is not part of the global atomic state. <dl class="function"> <dt id="c.drm_atomic_get_new_crtc_state"> struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * <code class="descname">drm_atomic_get_new_crtc_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_get_new_crtc_state" title="Permalink to this definition">¶</a></dt> <dd>get new crtc state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to grab</dd> </dl> Description This function returns the new crtc state for the given crtc, or NULL if the crtc is not part of the global atomic state. <dl class="function"> <dt id="c.drm_atomic_get_existing_plane_state"> struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * <code class="descname">drm_atomic_get_existing_plane_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_atomic_get_existing_plane_state" title="Permalink to this definition">¶</a></dt> <dd>get plane state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to grab</dd> </dl> Description This function returns the plane state for the given plane, or NULL if the plane is not part of the global atomic state. This function is deprecated, drm_atomic_get_old_plane_state or drm_atomic_get_new_plane_state should be used instead. <dl class="function"> <dt id="c.drm_atomic_get_old_plane_state"> struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * <code class="descname">drm_atomic_get_old_plane_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_atomic_get_old_plane_state" title="Permalink to this definition">¶</a></dt> <dd>get plane state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to grab</dd> </dl> Description This function returns the old plane state for the given plane, or NULL if the plane is not part of the global atomic state. <dl class="function"> <dt id="c.drm_atomic_get_new_plane_state"> struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * <code class="descname">drm_atomic_get_new_plane_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_atomic_get_new_plane_state" title="Permalink to this definition">¶</a></dt> <dd>get plane state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to grab</dd> </dl> Description This function returns the new plane state for the given plane, or NULL if the plane is not part of the global atomic state. <dl class="function"> <dt id="c.drm_atomic_get_existing_connector_state"> struct <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state">drm_connector_state</a> * <code class="descname">drm_atomic_get_existing_connector_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_atomic_get_existing_connector_state" title="Permalink to this definition">¶</a></dt> <dd>get connector state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to grab</dd> </dl> Description This function returns the connector state for the given connector, or NULL if the connector is not part of the global atomic state. This function is deprecated, drm_atomic_get_old_connector_state or drm_atomic_get_new_connector_state should be used instead. <dl class="function"> <dt id="c.drm_atomic_get_old_connector_state"> struct <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state">drm_connector_state</a> * <code class="descname">drm_atomic_get_old_connector_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_atomic_get_old_connector_state" title="Permalink to this definition">¶</a></dt> <dd>get connector state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to grab</dd> </dl> Description This function returns the old connector state for the given connector, or NULL if the connector is not part of the global atomic state. <dl class="function"> <dt id="c.drm_atomic_get_new_connector_state"> struct <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state">drm_connector_state</a> * <code class="descname">drm_atomic_get_new_connector_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_atomic_get_new_connector_state" title="Permalink to this definition">¶</a></dt> <dd>get connector state, if it exists </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to grab</dd> </dl> Description This function returns the new connector state for the given connector, or NULL if the connector is not part of the global atomic state. <dl class="function"> <dt id="c.__drm_atomic_get_current_plane_state"> const struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * <code class="descname">__drm_atomic_get_current_plane_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.__drm_atomic_get_current_plane_state" title="Permalink to this definition">¶</a></dt> <dd>get current plane state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to grab</dd> </dl> Description This function returns the plane state for the given plane, either from state, or if the plane isn’t part of the atomic state update, from plane. This is useful in atomic check callbacks, when drivers need to peek at, but not change, state of other planes, since it avoids threading an error code back up the call chain. WARNING: Note that this function is in general unsafe since it doesn’t check for the required locking for access state structures. Drivers must ensure that it is safe to access the returned state structure through other means. One common example is when planes are fixed to a single CRTC, and the driver knows that the CRTC lock is held already. In that case holding the CRTC lock gives a read-lock on all planes connected to that CRTC. But if planes can be reassigned things get more tricky. In that case it’s better to use drm_atomic_get_plane_state and wire up full error handling. Return Read-only pointer to the current plane state. <dl class="function"> <dt id="c.for_each_oldnew_connector_in_state"> <code class="descname">for_each_oldnew_connector_in_state</code>(__state, connector, old_connector_state, new_connector_state, __i)<a class="headerlink" href="#c.for_each_oldnew_connector_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all connectors in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">connector</code></dt> <dd><a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_connector_state</code></dt> <dd><a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">new_connector_state</code></dt> <dd><a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all connectors in an atomic update, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions. <dl class="function"> <dt id="c.for_each_old_connector_in_state"> <code class="descname">for_each_old_connector_in_state</code>(__state, connector, old_connector_state, __i)<a class="headerlink" href="#c.for_each_old_connector_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all connectors in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">connector</code></dt> <dd><a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_connector_state</code></dt> <dd><a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all connectors in an atomic update, tracking only the old state. This is useful in disable functions, where we need the old state the hardware is still in. <dl class="function"> <dt id="c.for_each_new_connector_in_state"> <code class="descname">for_each_new_connector_in_state</code>(__state, connector, new_connector_state, __i)<a class="headerlink" href="#c.for_each_new_connector_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all connectors in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">connector</code></dt> <dd><a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> iteration cursor</dd> <dt><code class="docutils literal">new_connector_state</code></dt> <dd><a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all connectors in an atomic update, tracking only the new state. This is useful in enable functions, where we need the new state the hardware should be in when the atomic commit operation has completed. <dl class="function"> <dt id="c.for_each_oldnew_crtc_in_state"> <code class="descname">for_each_oldnew_crtc_in_state</code>(__state, crtc, old_crtc_state, new_crtc_state, __i)<a class="headerlink" href="#c.for_each_oldnew_crtc_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all CRTCs in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">crtc</code></dt> <dd><a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_crtc_state</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">new_crtc_state</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all CRTCs in an atomic update, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions. <dl class="function"> <dt id="c.for_each_old_crtc_in_state"> <code class="descname">for_each_old_crtc_in_state</code>(__state, crtc, old_crtc_state, __i)<a class="headerlink" href="#c.for_each_old_crtc_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all CRTCs in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">crtc</code></dt> <dd><a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_crtc_state</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all CRTCs in an atomic update, tracking only the old state. This is useful in disable functions, where we need the old state the hardware is still in. <dl class="function"> <dt id="c.for_each_new_crtc_in_state"> <code class="descname">for_each_new_crtc_in_state</code>(__state, crtc, new_crtc_state, __i)<a class="headerlink" href="#c.for_each_new_crtc_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all CRTCs in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">crtc</code></dt> <dd><a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> iteration cursor</dd> <dt><code class="docutils literal">new_crtc_state</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all CRTCs in an atomic update, tracking only the new state. This is useful in enable functions, where we need the new state the hardware should be in when the atomic commit operation has completed. <dl class="function"> <dt id="c.for_each_oldnew_plane_in_state"> <code class="descname">for_each_oldnew_plane_in_state</code>(__state, plane, old_plane_state, new_plane_state, __i)<a class="headerlink" href="#c.for_each_oldnew_plane_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">plane</code></dt> <dd><a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">new_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all planes in an atomic update, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions. <dl class="function"> <dt id="c.for_each_oldnew_plane_in_state_reverse"> <code class="descname">for_each_oldnew_plane_in_state_reverse</code>(__state, plane, old_plane_state, new_plane_state, __i)<a class="headerlink" href="#c.for_each_oldnew_plane_in_state_reverse" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes in an atomic update in reverse order </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">plane</code></dt> <dd><a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">new_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all planes in an atomic update in reverse order, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions. <dl class="function"> <dt id="c.for_each_old_plane_in_state"> <code class="descname">for_each_old_plane_in_state</code>(__state, plane, old_plane_state, __i)<a class="headerlink" href="#c.for_each_old_plane_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">plane</code></dt> <dd><a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all planes in an atomic update, tracking only the old state. This is useful in disable functions, where we need the old state the hardware is still in. <dl class="function"> <dt id="c.for_each_new_plane_in_state"> <code class="descname">for_each_new_plane_in_state</code>(__state, plane, new_plane_state, __i)<a class="headerlink" href="#c.for_each_new_plane_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">plane</code></dt> <dd><a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> iteration cursor</dd> <dt><code class="docutils literal">new_plane_state</code></dt> <dd><a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all planes in an atomic update, tracking only the new state. This is useful in enable functions, where we need the new state the hardware should be in when the atomic commit operation has completed. <dl class="function"> <dt id="c.for_each_oldnew_private_obj_in_state"> <code class="descname">for_each_oldnew_private_obj_in_state</code>(__state, obj, old_obj_state, new_obj_state, __i)<a class="headerlink" href="#c.for_each_oldnew_private_obj_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all private objects in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">obj</code></dt> <dd><a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">struct drm_private_obj</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_obj_state</code></dt> <dd><a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">struct drm_private_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">new_obj_state</code></dt> <dd><a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">struct drm_private_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all private objects in an atomic update, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions. <dl class="function"> <dt id="c.for_each_old_private_obj_in_state"> <code class="descname">for_each_old_private_obj_in_state</code>(__state, obj, old_obj_state, __i)<a class="headerlink" href="#c.for_each_old_private_obj_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all private objects in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">obj</code></dt> <dd><a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">struct drm_private_obj</code></a> iteration cursor</dd> <dt><code class="docutils literal">old_obj_state</code></dt> <dd><a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">struct drm_private_state</code></a> iteration cursor for the old state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all private objects in an atomic update, tracking only the old state. This is useful in disable functions, where we need the old state the hardware is still in. <dl class="function"> <dt id="c.for_each_new_private_obj_in_state"> <code class="descname">for_each_new_private_obj_in_state</code>(__state, obj, new_obj_state, __i)<a class="headerlink" href="#c.for_each_new_private_obj_in_state" title="Permalink to this definition">¶</a></dt> <dd>iterate over all private objects in an atomic update </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">__state</code></dt> <dd><a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointer</dd> <dt><code class="docutils literal">obj</code></dt> <dd><a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj"><code class="xref c c-type docutils literal">struct drm_private_obj</code></a> iteration cursor</dd> <dt><code class="docutils literal">new_obj_state</code></dt> <dd><a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">struct drm_private_state</code></a> iteration cursor for the new state</dd> <dt><code class="docutils literal">__i</code></dt> <dd>int iteration cursor, for macro-internal use</dd> </dl> Description This iterates over all private objects in an atomic update, tracking only the new state. This is useful in enable functions, where we need the new state the hardware should be in when the atomic commit operation has completed. <dl class="function"> <dt id="c.drm_atomic_crtc_needs_modeset"> bool <code class="descname">drm_atomic_crtc_needs_modeset</code>(const struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * state)<a class="headerlink" href="#c.drm_atomic_crtc_needs_modeset" title="Permalink to this definition">¶</a></dt> <dd>compute combined modeset need </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_crtc_state * state</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state</code></a> for the CRTC</dd> </dl> Description To give drivers flexibility <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> has 3 booleans to track whether the state CRTC changed enough to need a full modeset cycle: mode_changed, active_changed and connectors_changed. This helper simply combines these three to compute the overall need for a modeset for state. The atomic helper code sets these booleans, but drivers can and should change them appropriately to accurately represent whether a modeset is really needed. In general, drivers should avoid full modesets whenever possible. For example if the CRTC mode has changed, and the hardware is able to enact the requested mode change without going through a full modeset, the driver should clear mode_changed in its <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check</code></a> implementation. <dl class="function"> <dt id="c.drm_atomic_state_default_release"> void <code class="descname">drm_atomic_state_default_release</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_default_release" title="Permalink to this definition">¶</a></dt> <dd>release memory initialized by drm_atomic_state_init </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> </dl> Description Free all the memory allocated by drm_atomic_state_init. This should only be used by drivers which are still subclassing <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> and haven’t switched to <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> yet. <dl class="function"> <dt id="c.drm_atomic_state_init"> int <code class="descname">drm_atomic_state_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_init" title="Permalink to this definition">¶</a></dt> <dd>init new atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> </dl> Description Default implementation for filling in a new atomic state. This should only be used by drivers which are still subclassing <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> and haven’t switched to <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> yet. <dl class="function"> <dt id="c.drm_atomic_state_alloc"> struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * <code class="descname">drm_atomic_state_alloc</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_atomic_state_alloc" title="Permalink to this definition">¶</a></dt> <dd>allocate atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description This allocates an empty atomic state to track updates. <dl class="function"> <dt id="c.drm_atomic_state_default_clear"> void <code class="descname">drm_atomic_state_default_clear</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_default_clear" title="Permalink to this definition">¶</a></dt> <dd>clear base atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> </dl> Description Default implementation for clearing atomic state. This should only be used by drivers which are still subclassing <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a> and haven’t switched to <a class="reference internal" href="#c.drm_private_state" title="drm_private_state"><code class="xref c c-type docutils literal">drm_private_state</code></a> yet. <dl class="function"> <dt id="c.drm_atomic_state_clear"> void <code class="descname">drm_atomic_state_clear</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_state_clear" title="Permalink to this definition">¶</a></dt> <dd>clear state object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> </dl> Description When the w/w mutex algorithm detects a deadlock we need to back off and drop all locks. So someone else could sneak in and change the current modeset configuration. Which means that all the state assembled in state is no longer an atomic update to the current state, but to some arbitrary earlier state. Which could break assumptions the driver’s <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check</code></a> likely relies on. Hence we must clear all cached state and completely start over, using this function. <dl class="function"> <dt id="c.__drm_atomic_state_free"> void <code class="descname">__drm_atomic_state_free</code>(struct kref * ref)<a class="headerlink" href="#c.__drm_atomic_state_free" title="Permalink to this definition">¶</a></dt> <dd>free all memory for an atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct kref * ref</code></dt> <dd>This atomic state to deallocate</dd> </dl> Description This frees all memory associated with an atomic state, including all the per-object state for planes, crtcs and connectors. <dl class="function"> <dt id="c.drm_atomic_get_crtc_state"> struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * <code class="descname">drm_atomic_get_crtc_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_get_crtc_state" title="Permalink to this definition">¶</a></dt> <dd>get crtc state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to get state object for</dd> </dl> Description This function returns the crtc state for the given crtc, allocating it if needed. It will also grab the relevant crtc lock to make sure that the state is consistent. Return Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_set_mode_for_crtc"> int <code class="descname">drm_atomic_set_mode_for_crtc</code>(struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * state, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_atomic_set_mode_for_crtc" title="Permalink to this definition">¶</a></dt> <dd>set mode for CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc_state * state</code></dt> <dd>the CRTC whose incoming state to update</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>kernel-internal mode to use for the CRTC, or NULL to disable</dd> </dl> Description Set a mode (originating from the kernel) on the desired CRTC state and update the enable property. Return Zero on success, error code on failure. Cannot return -EDEADLK. <dl class="function"> <dt id="c.drm_atomic_set_mode_prop_for_crtc"> int <code class="descname">drm_atomic_set_mode_prop_for_crtc</code>(struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * state, struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * blob)<a class="headerlink" href="#c.drm_atomic_set_mode_prop_for_crtc" title="Permalink to this definition">¶</a></dt> <dd>set mode for CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc_state * state</code></dt> <dd>the CRTC whose incoming state to update</dd> <dt><code class="docutils literal">struct drm_property_blob * blob</code></dt> <dd>pointer to blob property to use for mode</dd> </dl> Description Set a mode (originating from a blob property) on the desired CRTC state. This function will take a reference on the blob property for the CRTC state, and release the reference held on the state’s existing mode property, if any was set. Return Zero on success, error code on failure. Cannot return -EDEADLK. <dl class="function"> <dt id="c.drm_atomic_crtc_set_property"> int <code class="descname">drm_atomic_crtc_set_property</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state">drm_crtc_state</a> * state, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint64_t val)<a class="headerlink" href="#c.drm_atomic_crtc_set_property" title="Permalink to this definition">¶</a></dt> <dd>set property on CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>the drm CRTC to set a property on</dd> <dt><code class="docutils literal">struct drm_crtc_state * state</code></dt> <dd>the state object to update with the new property value</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>the property to set</dd> <dt><code class="docutils literal">uint64_t val</code></dt> <dd>the new property value</dd> </dl> Description This function handles generic/core properties and calls out to driver’s <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.atomic_set_property</code></a> for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly. Return Zero on success, error code on failure <dl class="function"> <dt id="c.drm_atomic_get_plane_state"> struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * <code class="descname">drm_atomic_get_plane_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_atomic_get_plane_state" title="Permalink to this definition">¶</a></dt> <dd>get plane state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to get state object for</dd> </dl> Description This function returns the plane state for the given plane, allocating it if needed. It will also grab the relevant plane lock to make sure that the state is consistent. Return Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_private_obj_init"> void <code class="descname">drm_atomic_private_obj_init</code>(struct <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj">drm_private_obj</a> * obj, struct <a class="reference internal" href="#c.drm_private_state" title="drm_private_state">drm_private_state</a> * state, const struct <a class="reference internal" href="#c.drm_private_state_funcs" title="drm_private_state_funcs">drm_private_state_funcs</a> * funcs)<a class="headerlink" href="#c.drm_atomic_private_obj_init" title="Permalink to this definition">¶</a></dt> <dd>initialize private object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_private_obj * obj</code></dt> <dd>private object</dd> <dt><code class="docutils literal">struct drm_private_state * state</code></dt> <dd>initial private object state</dd> <dt><code class="docutils literal">const struct drm_private_state_funcs * funcs</code></dt> <dd>pointer to the struct of function pointers that identify the object type</dd> </dl> Description Initialize the private object, which can be embedded into any driver private object that needs its own atomic state. <dl class="function"> <dt id="c.drm_atomic_private_obj_fini"> void <code class="descname">drm_atomic_private_obj_fini</code>(struct <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj">drm_private_obj</a> * obj)<a class="headerlink" href="#c.drm_atomic_private_obj_fini" title="Permalink to this definition">¶</a></dt> <dd>finalize private object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_private_obj * obj</code></dt> <dd>private object</dd> </dl> Description Finalize the private object. <dl class="function"> <dt id="c.drm_atomic_get_private_obj_state"> struct <a class="reference internal" href="#c.drm_private_state" title="drm_private_state">drm_private_state</a> * <code class="descname">drm_atomic_get_private_obj_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_private_obj" title="drm_private_obj">drm_private_obj</a> * obj)<a class="headerlink" href="#c.drm_atomic_get_private_obj_state" title="Permalink to this definition">¶</a></dt> <dd>get private object state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state</dd> <dt><code class="docutils literal">struct drm_private_obj * obj</code></dt> <dd>private object to get the state for</dd> </dl> Description This function returns the private object state for the given private object, allocating the state if needed. It does not grab any locks as the caller is expected to care of any required locking. Return Either the allocated state or the error code encoded into a pointer. <dl class="function"> <dt id="c.drm_atomic_get_connector_state"> struct <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state">drm_connector_state</a> * <code class="descname">drm_atomic_get_connector_state</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_atomic_get_connector_state" title="Permalink to this definition">¶</a></dt> <dd>get connector state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>global atomic state object</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to get state object for</dd> </dl> Description This function returns the connector state for the given connector, allocating it if needed. It will also grab the relevant connector lock to make sure that the state is consistent. Return Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_set_crtc_for_plane"> int <code class="descname">drm_atomic_set_crtc_for_plane</code>(struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * plane_state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_set_crtc_for_plane" title="Permalink to this definition">¶</a></dt> <dd>set crtc for plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane_state * plane_state</code></dt> <dd>the plane whose incoming state to update</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to use for the plane</dd> </dl> Description Changing the assigned crtc for a plane requires us to grab the lock and state for the new crtc, as needed. This function takes care of all these details besides updating the pointer in the state object itself. Return 0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_set_fb_for_plane"> void <code class="descname">drm_atomic_set_fb_for_plane</code>(struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * plane_state, struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_atomic_set_fb_for_plane" title="Permalink to this definition">¶</a></dt> <dd>set framebuffer for plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane_state * plane_state</code></dt> <dd>atomic state object for the plane</dd> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>fb to use for the plane</dd> </dl> Description Changing the assigned framebuffer for a plane requires us to grab a reference to the new fb and drop the reference to the old fb, if there is one. This function takes care of all these details besides updating the pointer in the state object itself. <dl class="function"> <dt id="c.drm_atomic_set_fence_for_plane"> void <code class="descname">drm_atomic_set_fence_for_plane</code>(struct <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state">drm_plane_state</a> * plane_state, struct <a class="reference internal" href="../driver-api/dma-buf.html#c.dma_fence" title="dma_fence">dma_fence</a> * fence)<a class="headerlink" href="#c.drm_atomic_set_fence_for_plane" title="Permalink to this definition">¶</a></dt> <dd>set fence for plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane_state * plane_state</code></dt> <dd>atomic state object for the plane</dd> <dt><code class="docutils literal">struct dma_fence * fence</code></dt> <dd>dma_fence to use for the plane</dd> </dl> Description Helper to setup the plane_state fence in case it is not set yet. By using this drivers doesn’t need to worry if the user choose implicit or explicit fencing. This function will not set the fence to the state if it was set via explicit fencing interfaces on the atomic ioctl. In that case it will drop the reference to the fence as we are not storing it anywhere. Otherwise, if <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state.fence</code></a> is not set this function we just set it with the received implicit fence. In both cases this function consumes a reference for fence. <dl class="function"> <dt id="c.drm_atomic_set_crtc_for_connector"> int <code class="descname">drm_atomic_set_crtc_for_connector</code>(struct <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state">drm_connector_state</a> * conn_state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_set_crtc_for_connector" title="Permalink to this definition">¶</a></dt> <dd>set crtc for connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector_state * conn_state</code></dt> <dd>atomic state object for the connector</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to use for the connector</dd> </dl> Description Changing the assigned crtc for a connector requires us to grab the lock and state for the new crtc, as needed. This function takes care of all these details besides updating the pointer in the state object itself. Return 0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_add_affected_connectors"> int <code class="descname">drm_atomic_add_affected_connectors</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_add_affected_connectors" title="Permalink to this definition">¶</a></dt> <dd>add connectors for crtc </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>DRM crtc</dd> </dl> Description This function walks the current configuration and adds all connectors currently using crtc to the atomic configuration state. Note that this function must acquire the connection mutex. This can potentially cause unneeded seralization if the update is just for the planes on one crtc. Hence drivers and helpers should only call this when really needed (e.g. when a full modeset needs to happen due to some change). Return 0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_add_affected_planes"> int <code class="descname">drm_atomic_add_affected_planes</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_atomic_add_affected_planes" title="Permalink to this definition">¶</a></dt> <dd>add planes for crtc </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>DRM crtc</dd> </dl> Description This function walks the current configuration and adds all planes currently used by crtc to the atomic configuration state. This is useful when an atomic commit also needs to check all currently enabled plane on crtc, e.g. when changing the mode. It’s also useful when re-enabling a CRTC to avoid special code to force-enable all planes. Since acquiring a plane state will always also acquire the w/w mutex of the current CRTC for that plane (if there is any) adding all the plane states for a CRTC will not reduce parallism of atomic updates. Return 0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal. <dl class="function"> <dt id="c.drm_atomic_check_only"> int <code class="descname">drm_atomic_check_only</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_check_only" title="Permalink to this definition">¶</a></dt> <dd>check whether a given config would work </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic configuration to check</dd> </dl> Description Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal. Return 0 on success, negative error code on failure. <dl class="function"> <dt id="c.drm_atomic_commit"> int <code class="descname">drm_atomic_commit</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_commit" title="Permalink to this definition">¶</a></dt> <dd>commit configuration atomically </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic configuration to check</dd> </dl> Description Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal. This function will take its own reference on state. Callers should always release their reference with <a class="reference internal" href="#c.drm_atomic_state_put" title="drm_atomic_state_put"><code class="xref c c-func docutils literal">drm_atomic_state_put()</code></a>. Return 0 on success, negative error code on failure. <dl class="function"> <dt id="c.drm_atomic_nonblocking_commit"> int <code class="descname">drm_atomic_nonblocking_commit</code>(struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_nonblocking_commit" title="Permalink to this definition">¶</a></dt> <dd>atomic nonblocking commit </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic configuration to check</dd> </dl> Description Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal. This function will take its own reference on state. Callers should always release their reference with <a class="reference internal" href="#c.drm_atomic_state_put" title="drm_atomic_state_put"><code class="xref c c-func docutils literal">drm_atomic_state_put()</code></a>. Return 0 on success, negative error code on failure. <dl class="function"> <dt id="c.drm_state_dump"> void <code class="descname">drm_state_dump</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_printer" title="drm_printer">drm_printer</a> * p)<a class="headerlink" href="#c.drm_state_dump" title="Permalink to this definition">¶</a></dt> <dd>dump entire device atomic state </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>the drm device</dd> <dt><code class="docutils literal">struct drm_printer * p</code></dt> <dd>where to print the state to</dd> </dl> Description Just for debugging. Drivers might want an option to dump state to dmesg in case of error irq’s. (Hint, you probably want to ratelimit this!) The caller must <a class="reference internal" href="#c.drm_modeset_lock_all" title="drm_modeset_lock_all"><code class="xref c c-func docutils literal">drm_modeset_lock_all()</code></a>, or if this is called from error irq handler, it should not be enabled by default. (Ie. if you are debugging errors you might not care that this is racey. But calling this without all modeset locks held is not inherently safe.) <dl class="function"> <dt id="c.drm_atomic_clean_old_fb"> void <code class="descname">drm_atomic_clean_old_fb</code>(struct drm_device * dev, unsigned plane_mask, int ret)<a class="headerlink" href="#c.drm_atomic_clean_old_fb" title="Permalink to this definition">¶</a></dt> <dd><ul class="simple"> <li>Unset old_fb pointers and set plane->fb pointers.</li> </ul> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device to check.</dd> <dt><code class="docutils literal">unsigned plane_mask</code></dt> <dd>plane mask for planes that were updated.</dd> <dt><code class="docutils literal">int ret</code></dt> <dd>return value, can be -EDEADLK for a retry.</dd> </dl> Description Before doing an update <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane.old_fb</code></a> is set to <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane.fb</code></a>, but before dropping the locks old_fb needs to be set to NULL and plane->fb updated. This is a common operation for each atomic update, so this call is split off as a helper. </div> </div> <div class="section" id="crtc-abstraction"> <h2>CRTC Abstraction<a class="headerlink" href="#crtc-abstraction" title="Permalink to this headline">¶</a></h2> A CRTC represents the overall display pipeline. It receives pixel data from <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> and blends them together. The <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode"><code class="xref c c-type docutils literal">drm_display_mode</code></a> is also attached to the CRTC, specifying display timings. On the output side the data is fed to one or more <a class="reference internal" href="#c.drm_encoder" title="drm_encoder"><code class="xref c c-type docutils literal">drm_encoder</code></a>, which are then each connected to one <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a>. To create a CRTC, a KMS drivers allocates and zeroes an instances of <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> (possibly as part of a larger structure) and registers it with a call to <a class="reference internal" href="#c.drm_crtc_init_with_planes" title="drm_crtc_init_with_planes"><code class="xref c c-func docutils literal">drm_crtc_init_with_planes()</code></a>. The CRTC is also the entry point for legacy modeset operations, see <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.set_config</code></a>, legacy plane operations, see <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.page_flip</code></a> and <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.cursor_set2</code></a>, and other legacy operations like <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.gamma_set</code></a>. For atomic drivers all these features are controlled through <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a> and <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check</code></a> and <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check</code></a>. <div class="section" id="crtc-functions-reference"> <h3>CRTC Functions Reference<a class="headerlink" href="#crtc-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_crtc_state"> struct <code class="descname">drm_crtc_state</code><a class="headerlink" href="#c.drm_crtc_state" title="Permalink to this definition">¶</a></dt> <dd>mutable CRTC state </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_crtc_state { struct drm_crtc *crtc; bool enable; bool active; bool planes_changed : 1; bool mode_changed : 1; bool active_changed : 1; bool connectors_changed : 1; bool zpos_changed : 1; bool color_mgmt_changed : 1; u32 plane_mask; u32 connector_mask; u32 encoder_mask; struct drm_display_mode adjusted_mode; struct drm_display_mode mode; struct drm_property_blob *mode_blob; struct drm_property_blob *degamma_lut; struct drm_property_blob *ctm; struct drm_property_blob *gamma_lut; u32 target_vblank; u32 pageflip_flags; struct drm_pending_vblank_event *event; struct drm_crtc_commit *commit; struct drm_atomic_state *state; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">crtc</code></dt> <dd>backpointer to the CRTC</dd> <dt><code class="docutils literal">enable</code></dt> <dd>whether the CRTC should be enabled, gates all other state</dd> <dt><code class="docutils literal">active</code></dt> <dd>whether the CRTC is actively displaying (used for DPMS)</dd> <dt><code class="docutils literal">planes_changed</code></dt> <dd>planes on this crtc are updated</dd> <dt><code class="docutils literal">mode_changed</code></dt> <dd>mode or enable has been changed</dd> <dt><code class="docutils literal">active_changed</code></dt> <dd>active has been toggled.</dd> <dt><code class="docutils literal">connectors_changed</code></dt> <dd>connectors to this crtc have been updated</dd> <dt><code class="docutils literal">zpos_changed</code></dt> <dd>zpos values of planes on this crtc have been updated</dd> <dt><code class="docutils literal">color_mgmt_changed</code></dt> <dd>color management properties have changed (degamma or gamma LUT or CSC matrix)</dd> <dt><code class="docutils literal">plane_mask</code></dt> <dd>bitmask of (1 << drm_plane_index(plane)) of attached planes</dd> <dt><code class="docutils literal">connector_mask</code></dt> <dd>bitmask of (1 << drm_connector_index(connector)) of attached connectors</dd> <dt><code class="docutils literal">encoder_mask</code></dt> <dd>bitmask of (1 << drm_encoder_index(encoder)) of attached encoders</dd> <dt><code class="docutils literal">adjusted_mode</code></dt> <dd>Internal display timings which can be used by the driver to handle differences between the mode requested by userspace in mode and what is actually programmed into the hardware. It is purely driver implementation defined what exactly this adjusted mode means. Usually it is used to store the hardware display timings used between the CRTC and encoder blocks.</dd> <dt><code class="docutils literal">mode</code></dt> <dd>Display timings requested by userspace. The driver should try to match the refresh rate as close as possible (but note that it’s undefined what exactly is close enough, e.g. some of the HDMI modes only differ in less than 1% of the refresh rate). The active width and height as observed by userspace for positioning planes must match exactly. For external connectors where the sink isn’t fixed (like with a built-in panel), this mode here should match the physical mode on the wire to the last details (i.e. including sync polarities and everything). </dd> <dt><code class="docutils literal">mode_blob</code></dt> <dd><a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob"><code class="xref c c-type docutils literal">drm_property_blob</code></a> for mode</dd> <dt><code class="docutils literal">degamma_lut</code></dt> <dd>Lookup table for converting framebuffer pixel data before apply the color conversion matrix ctm. See <a class="reference internal" href="#c.drm_crtc_enable_color_mgmt" title="drm_crtc_enable_color_mgmt"><code class="xref c c-func docutils literal">drm_crtc_enable_color_mgmt()</code></a>. The blob (if not NULL) is an array of <code class="xref c c-type docutils literal">struct drm_color_lut</code>.</dd> <dt><code class="docutils literal">ctm</code></dt> <dd>Color transformation matrix. See <a class="reference internal" href="#c.drm_crtc_enable_color_mgmt" title="drm_crtc_enable_color_mgmt"><code class="xref c c-func docutils literal">drm_crtc_enable_color_mgmt()</code></a>. The blob (if not NULL) is a <code class="xref c c-type docutils literal">struct drm_color_ctm</code>.</dd> <dt><code class="docutils literal">gamma_lut</code></dt> <dd>Lookup table for converting pixel data after the color conversion matrix ctm. See <a class="reference internal" href="#c.drm_crtc_enable_color_mgmt" title="drm_crtc_enable_color_mgmt"><code class="xref c c-func docutils literal">drm_crtc_enable_color_mgmt()</code></a>. The blob (if not NULL) is an array of <code class="xref c c-type docutils literal">struct drm_color_lut</code>.</dd> <dt><code class="docutils literal">target_vblank</code></dt> <dd>Target vertical blank period when a page flip should take effect.</dd> <dt><code class="docutils literal">pageflip_flags</code></dt> <dd>DRM_MODE_PAGE_FLIP_* flags, as passed to the page flip ioctl. Zero in any other case.</dd> <dt><code class="docutils literal">event</code></dt> <dd>Optional pointer to a DRM event to signal upon completion of the state update. The driver must send out the event when the atomic commit operation completes. There are two cases: <blockquote> <div><ul class="simple"> <li>The event is for a CRTC which is being disabled through this atomic commit. In that case the event can be send out any time after the hardware has stopped scanning out the current framebuffers. It should contain the timestamp and counter for the last vblank before the display pipeline was shut off. The simplest way to achieve that is calling <a class="reference internal" href="#c.drm_crtc_send_vblank_event" title="drm_crtc_send_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_send_vblank_event()</code></a> somewhen after <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> has been called.</li> <li>For a CRTC which is enabled at the end of the commit (even when it undergoes an full modeset) the vblank timestamp and counter must be for the vblank right before the first frame that scans out the new set of buffers. Again the event can only be sent out after the hardware has stopped scanning out the old buffers.</li> <li>Events for disabled CRTCs are not allowed, and drivers can ignore that case.</li> </ul> </div></blockquote> This can be handled by the <a class="reference internal" href="#c.drm_crtc_send_vblank_event" title="drm_crtc_send_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_send_vblank_event()</code></a> function, which the driver should call on the provided event upon completion of the atomic commit. Note that if the driver supports vblank signalling and timestamping the vblank counters and timestamps must agree with the ones returned from page flip events. With the current vblank helper infrastructure this can be achieved by holding a vblank reference while the page flip is pending, acquired through <a class="reference internal" href="#c.drm_crtc_vblank_get" title="drm_crtc_vblank_get"><code class="xref c c-func docutils literal">drm_crtc_vblank_get()</code></a> and released with <a class="reference internal" href="#c.drm_crtc_vblank_put" title="drm_crtc_vblank_put"><code class="xref c c-func docutils literal">drm_crtc_vblank_put()</code></a>. Drivers are free to implement their own vblank counter and timestamp tracking though, e.g. if they have accurate timestamp registers in hardware. For hardware which supports some means to synchronize vblank interrupt delivery with committing display state there’s also <a class="reference internal" href="#c.drm_crtc_arm_vblank_event" title="drm_crtc_arm_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_arm_vblank_event()</code></a>. See the documentation of that function for a detailed discussion of the constraints it needs to be used safely. If the device can’t notify of flip completion in a race-free way at all, then the event should be armed just after the page flip is committed. In the worst case the driver will send the event to userspace one frame too late. This doesn’t allow for a real atomic update, but it should avoid tearing. </dd> <dt><code class="docutils literal">commit</code></dt> <dd>This tracks how the commit for this update proceeds through the various phases. This is never cleared, except when we destroy the state, so that subsequent commits can synchronize with previous ones.</dd> <dt><code class="docutils literal">state</code></dt> <dd>backpointer to global drm_atomic_state</dd> </dl> Description Note that the distinction between enable and active is rather subtile: Flipping active while enable is set without changing anything else may never return in a failure from the <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check</code></a> callback. Userspace assumes that a DPMS On will always succeed. In other words: enable controls resource assignment, active controls the actual hardware state. The three booleans active_changed, connectors_changed and mode_changed are intended to indicate whether a full modeset is needed, rather than strictly describing what has changed in a commit. See also: <a class="reference internal" href="#c.drm_atomic_crtc_needs_modeset" title="drm_atomic_crtc_needs_modeset"><code class="xref c c-func docutils literal">drm_atomic_crtc_needs_modeset()</code></a> <dl class="type"> <dt id="c.drm_crtc_funcs"> struct <code class="descname">drm_crtc_funcs</code><a class="headerlink" href="#c.drm_crtc_funcs" title="Permalink to this definition">¶</a></dt> <dd>control CRTCs for a given device </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_crtc_funcs { void (*reset)(struct drm_crtc *crtc); int (*cursor_set)(struct drm_crtc *crtc, struct drm_file *file_priv, uint32_t handle, uint32_t width, uint32_t height); int (*cursor_set2)(struct drm_crtc *crtc, struct drm_file *file_priv,uint32_t handle, uint32_t width, uint32_t height, int32_t hot_x, int32_t hot_y); int (*cursor_move)(struct drm_crtc *crtc, int x, int y); int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,uint32_t size, struct drm_modeset_acquire_ctx *ctx); void (*destroy)(struct drm_crtc *crtc); int (*set_config)(struct drm_mode_set *set, struct drm_modeset_acquire_ctx *ctx); int (*page_flip)(struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags, struct drm_modeset_acquire_ctx *ctx); int (*page_flip_target)(struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags, uint32_t target, struct drm_modeset_acquire_ctx *ctx); int (*set_property)(struct drm_crtc *crtc, struct drm_property *property, uint64_t val); struct drm_crtc_state *(*atomic_duplicate_state)(struct drm_crtc *crtc); void (*atomic_destroy_state)(struct drm_crtc *crtc, struct drm_crtc_state *state); int (*atomic_set_property)(struct drm_crtc *crtc,struct drm_crtc_state *state,struct drm_property *property, uint64_t val); int (*atomic_get_property)(struct drm_crtc *crtc,const struct drm_crtc_state *state,struct drm_property *property, uint64_t *val); int (*late_register)(struct drm_crtc *crtc); void (*early_unregister)(struct drm_crtc *crtc); int (*set_crc_source)(struct drm_crtc *crtc, const char *source, size_t *values_cnt); void (*atomic_print_state)(struct drm_printer *p, const struct drm_crtc_state *state); u32 (*get_vblank_counter)(struct drm_crtc *crtc); int (*enable_vblank)(struct drm_crtc *crtc); void (*disable_vblank)(struct drm_crtc *crtc); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">reset</code></dt> <dd>Reset CRTC hardware and software state to off. This function isn’t called by the core directly, only through <a class="reference internal" href="#c.drm_mode_config_reset" title="drm_mode_config_reset"><code class="xref c c-func docutils literal">drm_mode_config_reset()</code></a>. It’s not a helper hook only for historical reasons. Atomic drivers can use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_crtc_reset" title="drm_atomic_helper_crtc_reset"><code class="xref c c-func docutils literal">drm_atomic_helper_crtc_reset()</code></a> to reset atomic state using this hook. </dd> <dt><code class="docutils literal">cursor_set</code></dt> <dd>Update the cursor image. The cursor position is relative to the CRTC and can be partially or fully outside of the visible area. Note that contrary to all other KMS functions the legacy cursor entry points don’t take a framebuffer object, but instead take directly a raw buffer object id from the driver’s buffer manager (which is either GEM or TTM for current drivers). This entry point is deprecated, drivers should instead implement universal plane support and register a proper cursor plane using <a class="reference internal" href="#c.drm_crtc_init_with_planes" title="drm_crtc_init_with_planes"><code class="xref c c-func docutils literal">drm_crtc_init_with_planes()</code></a>. This callback is optional RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">cursor_set2</code></dt> <dd>Update the cursor image, including hotspot information. The hotspot must not affect the cursor position in CRTC coordinates, but is only meant as a hint for virtualized display hardware to coordinate the guests and hosts cursor position. The cursor hotspot is relative to the cursor image. Otherwise this works exactly like cursor_set. This entry point is deprecated, drivers should instead implement universal plane support and register a proper cursor plane using <a class="reference internal" href="#c.drm_crtc_init_with_planes" title="drm_crtc_init_with_planes"><code class="xref c c-func docutils literal">drm_crtc_init_with_planes()</code></a>. This callback is optional. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">cursor_move</code></dt> <dd>Update the cursor position. The cursor does not need to be visible when this hook is called. This entry point is deprecated, drivers should instead implement universal plane support and register a proper cursor plane using <a class="reference internal" href="#c.drm_crtc_init_with_planes" title="drm_crtc_init_with_planes"><code class="xref c c-func docutils literal">drm_crtc_init_with_planes()</code></a>. This callback is optional. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">gamma_set</code></dt> <dd>Set gamma on the CRTC. This callback is optional. Atomic drivers who want to support gamma tables should implement the atomic color management support, enabled by calling <a class="reference internal" href="#c.drm_crtc_enable_color_mgmt" title="drm_crtc_enable_color_mgmt"><code class="xref c c-func docutils literal">drm_crtc_enable_color_mgmt()</code></a>, which then supports the legacy gamma interface through the <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_legacy_gamma_set" title="drm_atomic_helper_legacy_gamma_set"><code class="xref c c-func docutils literal">drm_atomic_helper_legacy_gamma_set()</code></a> compatibility implementation. </dd> <dt><code class="docutils literal">destroy</code></dt> <dd>Clean up plane resources. This is only called at driver unload time through <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a> since a CRTC cannot be hotplugged in DRM.</dd> <dt><code class="docutils literal">set_config</code></dt> <dd>This is the main legacy entry point to change the modeset state on a CRTC. All the details of the desired configuration are passed in a <a class="reference internal" href="#c.drm_mode_set" title="drm_mode_set"><code class="xref c c-type docutils literal">struct drm_mode_set</code></a> - see there for details. Drivers implementing atomic modeset should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_set_config" title="drm_atomic_helper_set_config"><code class="xref c c-func docutils literal">drm_atomic_helper_set_config()</code></a> to implement this hook. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">page_flip</code></dt> <dd>Legacy entry point to schedule a flip to the given framebuffer. Page flipping is a synchronization mechanism that replaces the frame buffer being scanned out by the CRTC with a new frame buffer during vertical blanking, avoiding tearing (except when requested otherwise through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application requests a page flip the DRM core verifies that the new frame buffer is large enough to be scanned out by the CRTC in the currently configured mode and then calls this hook with a pointer to the new frame buffer. The driver must wait for any pending rendering to the new framebuffer to complete before executing the flip. It should also wait for any pending rendering from other drivers if the underlying buffer is a shared dma-buf. An application can request to be notified when the page flip has completed. The drm core will supply a <code class="xref c c-type docutils literal">struct drm_event</code> in the event parameter in this case. This can be handled by the <a class="reference internal" href="#c.drm_crtc_send_vblank_event" title="drm_crtc_send_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_send_vblank_event()</code></a> function, which the driver should call on the provided event upon completion of the flip. Note that if the driver supports vblank signalling and timestamping the vblank counters and timestamps must agree with the ones returned from page flip events. With the current vblank helper infrastructure this can be achieved by holding a vblank reference while the page flip is pending, acquired through <a class="reference internal" href="#c.drm_crtc_vblank_get" title="drm_crtc_vblank_get"><code class="xref c c-func docutils literal">drm_crtc_vblank_get()</code></a> and released with <a class="reference internal" href="#c.drm_crtc_vblank_put" title="drm_crtc_vblank_put"><code class="xref c c-func docutils literal">drm_crtc_vblank_put()</code></a>. Drivers are free to implement their own vblank counter and timestamp tracking though, e.g. if they have accurate timestamp registers in hardware. This callback is optional. NOTE: Very early versions of the KMS ABI mandated that the driver must block (but not reject) any rendering to the old framebuffer until the flip operation has completed and the old framebuffer is no longer visible. This requirement has been lifted, and userspace is instead expected to request delivery of an event and wait with recycling old buffers until such has been received. RETURNS: 0 on success or a negative error code on failure. Note that if a page flip operation is already pending the callback should return -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode or just runtime disabled through DPMS respectively the new atomic “ACTIVE” state) should result in an -EINVAL error code. Note that <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_page_flip" title="drm_atomic_helper_page_flip"><code class="xref c c-func docutils literal">drm_atomic_helper_page_flip()</code></a> checks this already for atomic drivers. </dd> <dt><code class="docutils literal">page_flip_target</code></dt> <dd>Same as page_flip but with an additional parameter specifying the absolute target vertical blank period (as reported by <a class="reference internal" href="#c.drm_crtc_vblank_count" title="drm_crtc_vblank_count"><code class="xref c c-func docutils literal">drm_crtc_vblank_count()</code></a>) when the flip should take effect. Note that the core code calls drm_crtc_vblank_get before this entry point, and will call drm_crtc_vblank_put if this entry point returns any non-0 error code. It’s the driver’s responsibility to call drm_crtc_vblank_put after this entry point returns 0, typically when the flip completes. </dd> <dt><code class="docutils literal">set_property</code></dt> <dd>This is the legacy entry point to update a property attached to the CRTC. This callback is optional if the driver does not support any legacy driver-private properties. For atomic drivers it is not used because property handling is done entirely in the DRM core. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">atomic_duplicate_state</code></dt> <dd>Duplicate the current atomic state for this CRTC and return it. The core and helpers guarantee that any atomic state duplicated with this hook and still owned by the caller (i.e. not transferred to the driver by calling <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_commit</code></a>) will be cleaned up by calling the atomic_destroy_state hook in this structure. Atomic drivers which don’t subclass <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a> should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_crtc_duplicate_state" title="drm_atomic_helper_crtc_duplicate_state"><code class="xref c c-func docutils literal">drm_atomic_helper_crtc_duplicate_state()</code></a>. Drivers that subclass the state structure to extend it with driver-private state should use <a class="reference internal" href="drm-kms-helpers.html#c.__drm_atomic_helper_crtc_duplicate_state" title="__drm_atomic_helper_crtc_duplicate_state"><code class="xref c c-func docutils literal">__drm_atomic_helper_crtc_duplicate_state()</code></a> to make sure shared state is duplicated in a consistent fashion across drivers. It is an error to call this hook before <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.state</code></a> has been initialized correctly. NOTE: If the duplicate state references refcounted resources this hook must acquire a reference for each of them. The driver must release these references again in atomic_destroy_state. RETURNS: Duplicated atomic state or NULL when the allocation failed. </dd> <dt><code class="docutils literal">atomic_destroy_state</code></dt> <dd>Destroy a state duplicated with atomic_duplicate_state and release or unreference all resources it references</dd> <dt><code class="docutils literal">atomic_set_property</code></dt> <dd>Decode a driver-private property value and store the decoded value into the passed-in state structure. Since the atomic core decodes all standardized properties (even for extensions beyond the core set of properties which might not be implemented by all drivers) this requires drivers to subclass the state structure. Such driver-private properties should really only be implemented for truly hardware/vendor specific state. Instead it is preferred to standardize atomic extension and decode the properties used to expose such an extension in the core. Do not call this function directly, use <a class="reference internal" href="#c.drm_atomic_crtc_set_property" title="drm_atomic_crtc_set_property"><code class="xref c c-func docutils literal">drm_atomic_crtc_set_property()</code></a> instead. This callback is optional if the driver does not support any driver-private atomic properties. NOTE: This function is called in the state assembly phase of atomic modesets, which can be aborted for any reason (including on userspace’s request to just check whether a configuration would be possible). Drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in state parameter. Also since userspace controls in which order properties are set this function must not do any input validation (since the state update is incomplete and hence likely inconsistent). Instead any such input validation must be done in the various atomic_check callbacks. RETURNS: 0 if the property has been found, -EINVAL if the property isn’t implemented by the driver (which should never happen, the core only asks for properties attached to this CRTC). No other validation is allowed by the driver. The core already checks that the property value is within the range (integer, valid enum value, ...) the driver set when registering the property. </dd> <dt><code class="docutils literal">atomic_get_property</code></dt> <dd>Reads out the decoded driver-private property. This is used to implement the GETCRTC IOCTL. Do not call this function directly, use <code class="xref c c-func docutils literal">drm_atomic_crtc_get_property()</code> instead. This callback is optional if the driver does not support any driver-private atomic properties. RETURNS: 0 on success, -EINVAL if the property isn’t implemented by the driver (which should never happen, the core only asks for properties attached to this CRTC). </dd> <dt><code class="docutils literal">late_register</code></dt> <dd>This optional hook can be used to register additional userspace interfaces attached to the crtc like debugfs interfaces. It is called late in the driver load sequence from <a class="reference internal" href="drm-internals.html#c.drm_dev_register" title="drm_dev_register"><code class="xref c c-func docutils literal">drm_dev_register()</code></a>. Everything added from this callback should be unregistered in the early_unregister callback. Returns: 0 on success, or a negative error code on failure. </dd> <dt><code class="docutils literal">early_unregister</code></dt> <dd>This optional hook should be used to unregister the additional userspace interfaces attached to the crtc from late_register. It is called from <a class="reference internal" href="drm-internals.html#c.drm_dev_unregister" title="drm_dev_unregister"><code class="xref c c-func docutils literal">drm_dev_unregister()</code></a>, early in the driver unload sequence to disable userspace access before data structures are torndown.</dd> <dt><code class="docutils literal">set_crc_source</code></dt> <dd>Changes the source of CRC checksums of frames at the request of userspace, typically for testing purposes. The sources available are specific of each driver and a <code class="docutils literal">NULL</code> value indicates that CRC generation is to be switched off. When CRC generation is enabled, the driver should call <a class="reference internal" href="drm-uapi.html#c.drm_crtc_add_crc_entry" title="drm_crtc_add_crc_entry"><code class="xref c c-func docutils literal">drm_crtc_add_crc_entry()</code></a> at each frame, providing any information that characterizes the frame contents in the crcN arguments, as provided from the configured source. Drivers must accept an “auto” source name that will select a default source for this CRTC. Note that “auto” can depend upon the current modeset configuration, e.g. it could pick an encoder or output specific CRC sampling point. This callback is optional if the driver does not support any CRC generation functionality. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">atomic_print_state</code></dt> <dd>If driver subclasses <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">struct drm_crtc_state</code></a>, it should implement this optional hook for printing additional driver specific state. Do not call this directly, use <code class="xref c c-func docutils literal">drm_atomic_crtc_print_state()</code> instead. </dd> <dt><code class="docutils literal">get_vblank_counter</code></dt> <dd>Driver callback for fetching a raw hardware vblank counter for the CRTC. It’s meant to be used by new drivers as the replacement of <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.get_vblank_counter</code></a> hook. This callback is optional. If a device doesn’t have a hardware counter, the driver can simply leave the hook as NULL. The DRM core will account for missed vblank events while interrupts where disabled based on system timestamps. Wraparound handling and loss of events due to modesetting is dealt with in the DRM core code, as long as drivers call <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> and <a class="reference internal" href="#c.drm_crtc_vblank_on" title="drm_crtc_vblank_on"><code class="xref c c-func docutils literal">drm_crtc_vblank_on()</code></a> when disabling or enabling a CRTC. See also <code class="xref c c-type docutils literal">drm_device.vblank_disable_immediate</code> and <code class="xref c c-type docutils literal">drm_device.max_vblank_count</code>. Returns: Raw vblank counter value. </dd> <dt><code class="docutils literal">enable_vblank</code></dt> <dd>Enable vblank interrupts for the CRTC. It’s meant to be used by new drivers as the replacement of <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.enable_vblank</code></a> hook. Returns: Zero on success, appropriate errno if the vblank interrupt cannot be enabled. </dd> <dt><code class="docutils literal">disable_vblank</code></dt> <dd>Disable vblank interrupts for the CRTC. It’s meant to be used by new drivers as the replacement of <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.disable_vblank</code></a> hook.</dd> </dl> Description The drm_crtc_funcs structure is the central CRTC management structure in the DRM. Each CRTC controls one or more connectors (note that the name CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc. connectors, not just CRTs). Each driver is responsible for filling out this structure at startup time, in addition to providing other modesetting features, like i2c and DDC bus accessors. <dl class="type"> <dt id="c.drm_crtc"> struct <code class="descname">drm_crtc</code><a class="headerlink" href="#c.drm_crtc" title="Permalink to this definition">¶</a></dt> <dd>central CRTC control structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_crtc { struct drm_device *dev; struct device_node *port; struct list_head head; char *name; struct drm_modeset_lock mutex; struct drm_mode_object base; struct drm_plane *primary; struct drm_plane *cursor; unsigned index; int cursor_x; int cursor_y; bool enabled; struct drm_display_mode mode; struct drm_display_mode hwmode; int x, y; const struct drm_crtc_funcs *funcs; uint32_t gamma_size; uint16_t *gamma_store; const struct drm_crtc_helper_funcs *helper_private; struct drm_object_properties properties; struct drm_crtc_state *state; struct list_head commit_list; spinlock_t commit_lock; #ifdef CONFIG_DEBUG_FS; struct dentry *debugfs_entry; #endif; struct drm_crtc_crc crc; unsigned int fence_context; spinlock_t fence_lock; unsigned long fence_seqno; char timeline_name[32]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>parent DRM device</dd> <dt><code class="docutils literal">port</code></dt> <dd>OF node used by <code class="xref c c-func docutils literal">drm_of_find_possible_crtcs()</code></dd> <dt><code class="docutils literal">head</code></dt> <dd>list management</dd> <dt><code class="docutils literal">name</code></dt> <dd>human readable name, can be overwritten by the driver</dd> <dt><code class="docutils literal">mutex</code></dt> <dd>This provides a read lock for the overall CRTC state (mode, dpms state, ...) and a write lock for everything which can be update without a full modeset (fb, cursor data, CRTC properties ...). A full modeset also need to grab <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.connection_mutex</code></a>. For atomic drivers specifically this protects state. </dd> <dt><code class="docutils literal">base</code></dt> <dd>base KMS object for ID tracking etc.</dd> <dt><code class="docutils literal">primary</code></dt> <dd>primary plane for this CRTC</dd> <dt><code class="docutils literal">cursor</code></dt> <dd>cursor plane for this CRTC</dd> <dt><code class="docutils literal">index</code></dt> <dd>Position inside the mode_config.list, can be used as an array index. It is invariant over the lifetime of the CRTC.</dd> <dt><code class="docutils literal">cursor_x</code></dt> <dd>current x position of the cursor, used for universal cursor planes</dd> <dt><code class="docutils literal">cursor_y</code></dt> <dd>current y position of the cursor, used for universal cursor planes</dd> <dt><code class="docutils literal">enabled</code></dt> <dd>is this CRTC enabled?</dd> <dt><code class="docutils literal">mode</code></dt> <dd>current mode timings</dd> <dt><code class="docutils literal">hwmode</code></dt> <dd>mode timings as programmed to hw regs</dd> <dt><code class="docutils literal">x</code></dt> <dd>x position on screen</dd> <dt><code class="docutils literal">y</code></dt> <dd>y position on screen</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>CRTC control functions</dd> <dt><code class="docutils literal">gamma_size</code></dt> <dd>size of gamma ramp</dd> <dt><code class="docutils literal">gamma_store</code></dt> <dd>gamma ramp values</dd> <dt><code class="docutils literal">helper_private</code></dt> <dd>mid-layer private data</dd> <dt><code class="docutils literal">properties</code></dt> <dd>property tracking for this CRTC</dd> <dt><code class="docutils literal">state</code></dt> <dd>Current atomic state for this CRTC. This is protected by mutex. Note that nonblocking atomic commits access the current CRTC state without taking locks. Either by going through the <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointers, see <a class="reference internal" href="#c.for_each_oldnew_crtc_in_state" title="for_each_oldnew_crtc_in_state"><code class="xref c c-func docutils literal">for_each_oldnew_crtc_in_state()</code></a>, <a class="reference internal" href="#c.for_each_old_crtc_in_state" title="for_each_old_crtc_in_state"><code class="xref c c-func docutils literal">for_each_old_crtc_in_state()</code></a> and <a class="reference internal" href="#c.for_each_new_crtc_in_state" title="for_each_new_crtc_in_state"><code class="xref c c-func docutils literal">for_each_new_crtc_in_state()</code></a>. Or through careful ordering of atomic commit operations as implemented in the atomic helpers, see <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit"><code class="xref c c-type docutils literal">struct drm_crtc_commit</code></a>. </dd> <dt><code class="docutils literal">commit_list</code></dt> <dd>List of <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit"><code class="xref c c-type docutils literal">drm_crtc_commit</code></a> structures tracking pending commits. Protected by commit_lock. This list holds its own full reference, as does the ongoing commit. “Note that the commit for a state change is also tracked in <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.commit</code></a>. For accessing the immediately preceding commit in an atomic update it is recommended to just use that pointer in the old CRTC state, since accessing that doesn’t need any locking or list-walking. commit_list should only be used to stall for framebuffer cleanup that’s signalled through <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit"><code class="xref c c-type docutils literal">drm_crtc_commit.cleanup_done</code></a>.” </dd> <dt><code class="docutils literal">commit_lock</code></dt> <dd>Spinlock to protect commit_list.</dd> <dt><code class="docutils literal">debugfs_entry</code></dt> <dd>Debugfs directory for this CRTC.</dd> <dt><code class="docutils literal">crc</code></dt> <dd>Configuration settings of CRC capture.</dd> <dt><code class="docutils literal">fence_context</code></dt> <dd>timeline context used for fence operations.</dd> <dt><code class="docutils literal">fence_lock</code></dt> <dd>spinlock to protect the fences in the fence_context.</dd> <dt><code class="docutils literal">fence_seqno</code></dt> <dd>Seqno variable used as monotonic counter for the fences created on the CRTC’s timeline.</dd> <dt><code class="docutils literal">timeline_name</code></dt> <dd>The name of the CRTC’s fence timeline.</dd> </dl> Description Each CRTC may have one or more connectors associated with it. This structure allows the CRTC to be controlled. <dl class="type"> <dt id="c.drm_mode_set"> struct <code class="descname">drm_mode_set</code><a class="headerlink" href="#c.drm_mode_set" title="Permalink to this definition">¶</a></dt> <dd>new values for a CRTC config change </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_mode_set { struct drm_framebuffer *fb; struct drm_crtc *crtc; struct drm_display_mode *mode; uint32_t x; uint32_t y; struct drm_connector **connectors; size_t num_connectors; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">fb</code></dt> <dd>framebuffer to use for new config</dd> <dt><code class="docutils literal">crtc</code></dt> <dd>CRTC whose configuration we’re about to change</dd> <dt><code class="docutils literal">mode</code></dt> <dd>mode timings to use</dd> <dt><code class="docutils literal">x</code></dt> <dd>position of this CRTC relative to fb</dd> <dt><code class="docutils literal">y</code></dt> <dd>position of this CRTC relative to fb</dd> <dt><code class="docutils literal">connectors</code></dt> <dd>array of connectors to drive with this CRTC if possible</dd> <dt><code class="docutils literal">num_connectors</code></dt> <dd>size of connectors array</dd> </dl> Description This represents a modeset configuration for the legacy SETCRTC ioctl and is also used internally. Atomic drivers instead use <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">drm_atomic_state</code></a>. <dl class="function"> <dt id="c.drm_crtc_index"> unsigned int <code class="descname">drm_crtc_index</code>(const struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_index" title="Permalink to this definition">¶</a></dt> <dd>find the index of a registered CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_crtc * crtc</code></dt> <dd>CRTC to find index for</dd> </dl> Description Given a registered CRTC, return the index of that CRTC within a DRM device’s list of CRTCs. <dl class="function"> <dt id="c.drm_crtc_mask"> uint32_t <code class="descname">drm_crtc_mask</code>(const struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_mask" title="Permalink to this definition">¶</a></dt> <dd>find the mask of a registered CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_crtc * crtc</code></dt> <dd>CRTC to find mask for</dd> </dl> Description Given a registered CRTC, return the mask bit of that CRTC for an encoder’s possible_crtcs field. <dl class="function"> <dt id="c.drm_crtc_find"> struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * <code class="descname">drm_crtc_find</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_crtc_find" title="Permalink to this definition">¶</a></dt> <dd>look up a CRTC object from its ID </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd><a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object"><code class="xref c c-type docutils literal">drm_mode_object</code></a> ID</dd> </dl> Description This can be used to look up a CRTC from its userspace ID. Only used by drivers for legacy IOCTLs and interface, nowadays extensions to the KMS userspace interface should be done using <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a>. <dl class="function"> <dt id="c.drm_for_each_crtc"> <code class="descname">drm_for_each_crtc</code>(crtc, dev)<a class="headerlink" href="#c.drm_for_each_crtc" title="Permalink to this definition">¶</a></dt> <dd>iterate over all CRTCs </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">crtc</code></dt> <dd>a <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> as the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the <code class="xref c c-type docutils literal">struct drm_device</code></dd> </dl> Description Iterate over all CRTCs of dev. <dl class="function"> <dt id="c.drm_crtc_from_index"> struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * <code class="descname">drm_crtc_from_index</code>(struct drm_device * dev, int idx)<a class="headerlink" href="#c.drm_crtc_from_index" title="Permalink to this definition">¶</a></dt> <dd>find the registered CRTC at an index </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">int idx</code></dt> <dd>index of registered CRTC to find for</dd> </dl> Description Given a CRTC index, return the registered CRTC from DRM device’s list of CRTCs with matching index. This is the inverse of <a class="reference internal" href="#c.drm_crtc_index" title="drm_crtc_index"><code class="xref c c-func docutils literal">drm_crtc_index()</code></a>. It’s useful in the vblank callbacks (like <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.enable_vblank</code></a> or <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.disable_vblank</code></a>), since that still deals with indices instead of pointers to <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>.” <dl class="function"> <dt id="c.drm_crtc_force_disable"> int <code class="descname">drm_crtc_force_disable</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_force_disable" title="Permalink to this definition">¶</a></dt> <dd>Forcibly turn off a CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC to turn off</dd> </dl> Note This should only be used by non-atomic legacy drivers. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_crtc_force_disable_all"> int <code class="descname">drm_crtc_force_disable_all</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_crtc_force_disable_all" title="Permalink to this definition">¶</a></dt> <dd>Forcibly turn off all enabled CRTCs </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device whose CRTCs to turn off</dd> </dl> Description Drivers may want to call this on unload to ensure that all displays are unlit and the GPU is in a consistent, low power state. Takes modeset locks. Note This should only be used by non-atomic legacy drivers. For an atomic version look at <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_shutdown" title="drm_atomic_helper_shutdown"><code class="xref c c-func docutils literal">drm_atomic_helper_shutdown()</code></a>. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_crtc_init_with_planes"> int <code class="descname">drm_crtc_init_with_planes</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * primary, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * cursor, const struct <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs">drm_crtc_funcs</a> * funcs, const char * name, ...)<a class="headerlink" href="#c.drm_crtc_init_with_planes" title="Permalink to this definition">¶</a></dt> <dd>Initialise a new CRTC object with specified primary and cursor planes. </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC object to init</dd> <dt><code class="docutils literal">struct drm_plane * primary</code></dt> <dd>Primary plane for CRTC</dd> <dt><code class="docutils literal">struct drm_plane * cursor</code></dt> <dd>Cursor plane for CRTC</dd> <dt><code class="docutils literal">const struct drm_crtc_funcs * funcs</code></dt> <dd>callbacks for the new CRTC</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>printf style format string for the CRTC name, or NULL for default name</dd> <dt><code class="docutils literal">...</code></dt> <dd>variable arguments</dd> </dl> Description Inits a new object created as base part of a driver crtc object. Drivers should use this function instead of <a class="reference internal" href="drm-kms-helpers.html#c.drm_crtc_init" title="drm_crtc_init"><code class="xref c c-func docutils literal">drm_crtc_init()</code></a>, which is only provided for backwards compatibility with drivers which do not yet support universal planes). For really simple hardware which has only 1 plane look at <a class="reference internal" href="drm-kms-helpers.html#c.drm_simple_display_pipe_init" title="drm_simple_display_pipe_init"><code class="xref c c-func docutils literal">drm_simple_display_pipe_init()</code></a> instead. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_crtc_cleanup"> void <code class="descname">drm_crtc_cleanup</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_cleanup" title="Permalink to this definition">¶</a></dt> <dd>Clean up the core crtc usage </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC to cleanup</dd> </dl> Description This function cleans up crtc and removes it from the DRM mode setting core. Note that the function does not free the crtc structure itself, this is the responsibility of the caller. <dl class="function"> <dt id="c.drm_mode_set_config_internal"> int <code class="descname">drm_mode_set_config_internal</code>(struct <a class="reference internal" href="#c.drm_mode_set" title="drm_mode_set">drm_mode_set</a> * set)<a class="headerlink" href="#c.drm_mode_set_config_internal" title="Permalink to this definition">¶</a></dt> <dd>helper to call <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.set_config</code></a> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_mode_set * set</code></dt> <dd>modeset config to set</dd> </dl> Description This is a little helper to wrap internal calls to the <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.set_config</code></a> driver interface. The only thing it adds is correct refcounting dance. This should only be used by non-atomic legacy drivers. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_crtc_check_viewport"> int <code class="descname">drm_crtc_check_viewport</code>(const struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, int x, int y, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode, const struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_crtc_check_viewport" title="Permalink to this definition">¶</a></dt> <dd>Checks that a framebuffer is big enough for the CRTC viewport </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_crtc * crtc</code></dt> <dd>CRTC that framebuffer will be displayed on</dd> <dt><code class="docutils literal">int x</code></dt> <dd>x panning</dd> <dt><code class="docutils literal">int y</code></dt> <dd>y panning</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode that framebuffer will be displayed under</dd> <dt><code class="docutils literal">const struct drm_framebuffer * fb</code></dt> <dd>framebuffer to check size of</dd> </dl> </div> </div> <div class="section" id="frame-buffer-abstraction"> <h2>Frame Buffer Abstraction<a class="headerlink" href="#frame-buffer-abstraction" title="Permalink to this headline">¶</a></h2> Frame buffers are abstract memory objects that provide a source of pixels to scanout to a CRTC. Applications explicitly request the creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and receive an opaque handle that can be passed to the KMS CRTC control, plane configuration and page flip functions. Frame buffers rely on the underlying memory manager for allocating backing storage. When creating a frame buffer applications pass a memory handle (or a list of memory handles for multi-planar formats) through the <code class="xref c c-type docutils literal">struct drm_mode_fb_cmd2</code> argument. For drivers using GEM as their userspace buffer management interface this would be a GEM handle. Drivers are however free to use their own backing storage object handles, e.g. vmwgfx directly exposes special TTM handles to userspace and so expects TTM handles in the create ioctl and not GEM handles. Framebuffers are tracked with <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">struct drm_framebuffer</code></a>. They are published using <a class="reference internal" href="#c.drm_framebuffer_init" title="drm_framebuffer_init"><code class="xref c c-func docutils literal">drm_framebuffer_init()</code></a> - after calling that function userspace can use and access the framebuffer object. The helper function <a class="reference internal" href="drm-kms-helpers.html#c.drm_helper_mode_fill_fb_struct" title="drm_helper_mode_fill_fb_struct"><code class="xref c c-func docutils literal">drm_helper_mode_fill_fb_struct()</code></a> can be used to pre-fill the required metadata fields. The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with <a class="reference internal" href="#c.drm_framebuffer_get" title="drm_framebuffer_get"><code class="xref c c-func docutils literal">drm_framebuffer_get()</code></a> and drop them again with <a class="reference internal" href="#c.drm_framebuffer_put" title="drm_framebuffer_put"><code class="xref c c-func docutils literal">drm_framebuffer_put()</code></a>. For driver-private framebuffers for which the last reference is never dropped (e.g. for the fbdev framebuffer when the struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">struct drm_framebuffer</code></a> is embedded into the fbdev helper struct) drivers can manually clean up a framebuffer at module unload time with <a class="reference internal" href="#c.drm_framebuffer_unregister_private" title="drm_framebuffer_unregister_private"><code class="xref c c-func docutils literal">drm_framebuffer_unregister_private()</code></a>. But doing this is not recommended, and it’s better to have a normal free-standing <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">struct drm_framebuffer</code></a>. <div class="section" id="frame-buffer-functions-reference"> <h3>Frame Buffer Functions Reference<a class="headerlink" href="#frame-buffer-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_framebuffer_funcs"> struct <code class="descname">drm_framebuffer_funcs</code><a class="headerlink" href="#c.drm_framebuffer_funcs" title="Permalink to this definition">¶</a></dt> <dd>framebuffer hooks </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_framebuffer_funcs { void (*destroy)(struct drm_framebuffer *framebuffer); int (*create_handle)(struct drm_framebuffer *fb,struct drm_file *file_priv, unsigned int *handle); int (*dirty)(struct drm_framebuffer *framebuffer,struct drm_file *file_priv, unsigned flags,unsigned color, struct drm_clip_rect *clips, unsigned num_clips); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">destroy</code></dt> <dd>Clean up framebuffer resources, specifically also unreference the backing storage. The core guarantees to call this function for every framebuffer successfully created by calling <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.fb_create</code></a>. Drivers must also call <a class="reference internal" href="#c.drm_framebuffer_cleanup" title="drm_framebuffer_cleanup"><code class="xref c c-func docutils literal">drm_framebuffer_cleanup()</code></a> to release DRM core resources for this framebuffer.</dd> <dt><code class="docutils literal">create_handle</code></dt> <dd>Create a buffer handle in the driver-specific buffer manager (either GEM or TTM) valid for the passed-in <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file"><code class="xref c c-type docutils literal">struct drm_file</code></a>. This is used by the core to implement the GETFB IOCTL, which returns (for sufficiently priviledged user) also a native buffer handle. This can be used for seamless transitions between modesetting clients by copying the current screen contents to a private buffer and blending between that and the new contents. GEM based drivers should call <a class="reference internal" href="drm-mm.html#c.drm_gem_handle_create" title="drm_gem_handle_create"><code class="xref c c-func docutils literal">drm_gem_handle_create()</code></a> to create the handle. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">dirty</code></dt> <dd>Optional callback for the dirty fb IOCTL. Userspace can notify the driver via this callback that an area of the framebuffer has changed and should be flushed to the display hardware. This can also be used internally, e.g. by the fbdev emulation, though that’s not the case currently. See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd for more information as all the semantics and arguments have a one to one mapping on this function. RETURNS: 0 on success or a negative error code on failure. </dd> </dl> <dl class="type"> <dt id="c.drm_framebuffer"> struct <code class="descname">drm_framebuffer</code><a class="headerlink" href="#c.drm_framebuffer" title="Permalink to this definition">¶</a></dt> <dd>frame buffer object </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_framebuffer { struct drm_device *dev; struct list_head head; struct drm_mode_object base; char comm[TASK_COMM_LEN]; const struct drm_format_info *format; const struct drm_framebuffer_funcs *funcs; unsigned int pitches[4]; unsigned int offsets[4]; uint64_t modifier; unsigned int width; unsigned int height; int flags; int hot_x; int hot_y; struct list_head filp_head; struct drm_gem_object *obj[4]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>DRM device this framebuffer belongs to</dd> <dt><code class="docutils literal">head</code></dt> <dd>Place on the <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.fb_list</code></a>, access protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.fb_lock</code></a>.</dd> <dt><code class="docutils literal">base</code></dt> <dd>base modeset object structure, contains the reference count.</dd> <dt><code class="docutils literal">comm</code></dt> <dd>Name of the process allocating the fb, used for fb dumping.</dd> <dt><code class="docutils literal">format</code></dt> <dd>framebuffer format information</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>framebuffer vfunc table</dd> <dt><code class="docutils literal">pitches</code></dt> <dd>Line stride per buffer. For userspace created object this is copied from drm_mode_fb_cmd2.</dd> <dt><code class="docutils literal">offsets</code></dt> <dd>Offset from buffer start to the actual pixel data in bytes, per buffer. For userspace created object this is copied from drm_mode_fb_cmd2. Note that this is a linear offset and does not take into account tiling or buffer laytou per modifier. It meant to be used when the actual pixel data for this framebuffer plane starts at an offset, e.g. when multiple planes are allocated within the same backing storage buffer object. For tiled layouts this generally means it offsets must at least be tile-size aligned, but hardware often has stricter requirements. This should not be used to specifiy x/y pixel offsets into the buffer data (even for linear buffers). Specifying an x/y pixel offset is instead done through the source rectangle in <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a>. </dd> <dt><code class="docutils literal">modifier</code></dt> <dd>Data layout modifier. This is used to describe tiling, or also special layouts (like compression) of auxiliary buffers. For userspace created object this is copied from drm_mode_fb_cmd2.</dd> <dt><code class="docutils literal">width</code></dt> <dd>Logical width of the visible area of the framebuffer, in pixels.</dd> <dt><code class="docutils literal">height</code></dt> <dd>Logical height of the visible area of the framebuffer, in pixels.</dd> <dt><code class="docutils literal">flags</code></dt> <dd>Framebuffer flags like DRM_MODE_FB_INTERLACED or DRM_MODE_FB_MODIFIERS.</dd> <dt><code class="docutils literal">hot_x</code></dt> <dd>X coordinate of the cursor hotspot. Used by the legacy cursor IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR universal plane.</dd> <dt><code class="docutils literal">hot_y</code></dt> <dd>Y coordinate of the cursor hotspot. Used by the legacy cursor IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR universal plane.</dd> <dt><code class="docutils literal">filp_head</code></dt> <dd>Placed on <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file"><code class="xref c c-type docutils literal">drm_file.fbs</code></a>, protected by <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file"><code class="xref c c-type docutils literal">drm_file.fbs_lock</code></a>.</dd> <dt><code class="docutils literal">obj</code></dt> <dd>GEM objects backing the framebuffer, one per plane (optional). This is used by the GEM framebuffer helpers, see e.g. <a class="reference internal" href="drm-kms-helpers.html#c.drm_gem_fb_create" title="drm_gem_fb_create"><code class="xref c c-func docutils literal">drm_gem_fb_create()</code></a>. </dd> </dl> Description Note that the fb is refcounted for the benefit of driver internals, for example some hw, disabling a CRTC/plane is asynchronous, and scanout does not actually complete until the next vblank. So some cleanup (like releasing the reference(s) on the backing GEM bo(s)) should be deferred. In cases like this, the driver would like to hold a ref to the fb even though it has already been removed from userspace perspective. See <a class="reference internal" href="#c.drm_framebuffer_get" title="drm_framebuffer_get"><code class="xref c c-func docutils literal">drm_framebuffer_get()</code></a> and <a class="reference internal" href="#c.drm_framebuffer_put" title="drm_framebuffer_put"><code class="xref c c-func docutils literal">drm_framebuffer_put()</code></a>. The refcount is stored inside the mode object base. <dl class="function"> <dt id="c.drm_framebuffer_get"> void <code class="descname">drm_framebuffer_get</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_get" title="Permalink to this definition">¶</a></dt> <dd>acquire a framebuffer reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>DRM framebuffer</dd> </dl> Description This function increments the framebuffer’s reference count. <dl class="function"> <dt id="c.drm_framebuffer_put"> void <code class="descname">drm_framebuffer_put</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_put" title="Permalink to this definition">¶</a></dt> <dd>release a framebuffer reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>DRM framebuffer</dd> </dl> Description This function decrements the framebuffer’s reference count and frees the framebuffer if the reference count drops to zero. <dl class="function"> <dt id="c.drm_framebuffer_reference"> void <code class="descname">drm_framebuffer_reference</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_reference" title="Permalink to this definition">¶</a></dt> <dd>acquire a framebuffer reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>DRM framebuffer</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_framebuffer_get" title="drm_framebuffer_get"><code class="xref c c-func docutils literal">drm_framebuffer_get()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_framebuffer_unreference"> void <code class="descname">drm_framebuffer_unreference</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_unreference" title="Permalink to this definition">¶</a></dt> <dd>release a framebuffer reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>DRM framebuffer</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_framebuffer_put" title="drm_framebuffer_put"><code class="xref c c-func docutils literal">drm_framebuffer_put()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_framebuffer_read_refcount"> uint32_t <code class="descname">drm_framebuffer_read_refcount</code>(const struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_read_refcount" title="Permalink to this definition">¶</a></dt> <dd>read the framebuffer reference count. </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_framebuffer * fb</code></dt> <dd>framebuffer</dd> </dl> Description This functions returns the framebuffer’s reference count. <dl class="function"> <dt id="c.drm_framebuffer_assign"> void <code class="descname">drm_framebuffer_assign</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> ** p, struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_assign" title="Permalink to this definition">¶</a></dt> <dd>store a reference to the fb </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer ** p</code></dt> <dd>location to store framebuffer</dd> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>new framebuffer (maybe NULL)</dd> </dl> Description This functions sets the location to store a reference to the framebuffer, unreferencing the framebuffer that was previously stored in that location. <dl class="function"> <dt id="c.drm_framebuffer_init"> int <code class="descname">drm_framebuffer_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb, const struct <a class="reference internal" href="#c.drm_framebuffer_funcs" title="drm_framebuffer_funcs">drm_framebuffer_funcs</a> * funcs)<a class="headerlink" href="#c.drm_framebuffer_init" title="Permalink to this definition">¶</a></dt> <dd>initialize a framebuffer </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>framebuffer to be initialized</dd> <dt><code class="docutils literal">const struct drm_framebuffer_funcs * funcs</code></dt> <dd>... with these functions</dd> </dl> Description Allocates an ID for the framebuffer’s parent mode object, sets its mode functions & device file and adds it to the master fd list. IMPORTANT: This functions publishes the fb and makes it available for concurrent access by other users. Which means by this point the fb _must_ be fully set up - since all the fb attributes are invariant over its lifetime, no further locking but only correct reference counting is required. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_framebuffer_lookup"> struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * <code class="descname">drm_framebuffer_lookup</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_framebuffer_lookup" title="Permalink to this definition">¶</a></dt> <dd>look up a drm framebuffer and grab a reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>id of the fb object</dd> </dl> Description If successful, this grabs an additional reference to the framebuffer - callers need to make sure to eventually unreference the returned framebuffer again, using <a class="reference internal" href="#c.drm_framebuffer_put" title="drm_framebuffer_put"><code class="xref c c-func docutils literal">drm_framebuffer_put()</code></a>. <dl class="function"> <dt id="c.drm_framebuffer_unregister_private"> void <code class="descname">drm_framebuffer_unregister_private</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_unregister_private" title="Permalink to this definition">¶</a></dt> <dd>unregister a private fb from the lookup idr </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>fb to unregister</dd> </dl> Description Drivers need to call this when cleaning up driver-private framebuffers, e.g. those used for fbdev. Note that the caller must hold a reference of it’s own, i.e. the object may not be destroyed through this call (since it’ll lead to a locking inversion). NOTE This function is deprecated. For driver-private framebuffers it is not recommended to embed a framebuffer struct info fbdev struct, instead, a framebuffer pointer is preferred and <a class="reference internal" href="#c.drm_framebuffer_put" title="drm_framebuffer_put"><code class="xref c c-func docutils literal">drm_framebuffer_put()</code></a> should be called when the framebuffer is to be cleaned up. <dl class="function"> <dt id="c.drm_framebuffer_cleanup"> void <code class="descname">drm_framebuffer_cleanup</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_cleanup" title="Permalink to this definition">¶</a></dt> <dd>remove a framebuffer object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>framebuffer to remove</dd> </dl> Description Cleanup framebuffer. This function is intended to be used from the drivers <a class="reference internal" href="#c.drm_framebuffer_funcs" title="drm_framebuffer_funcs"><code class="xref c c-type docutils literal">drm_framebuffer_funcs.destroy</code></a> callback. It can also be used to clean up driver private framebuffers embedded into a larger structure. Note that this function does not remove the fb from active usage - if it is still used anywhere, hilarity can ensue since userspace could call getfb on the id and get back -EINVAL. Obviously no concern at driver unload time. Also, the framebuffer will not be removed from the lookup idr - for user-created framebuffers this will happen in in the rmfb ioctl. For driver-private objects (e.g. for fbdev) drivers need to explicitly call drm_framebuffer_unregister_private. <dl class="function"> <dt id="c.drm_framebuffer_remove"> void <code class="descname">drm_framebuffer_remove</code>(struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb)<a class="headerlink" href="#c.drm_framebuffer_remove" title="Permalink to this definition">¶</a></dt> <dd>remove and unreference a framebuffer object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_framebuffer * fb</code></dt> <dd>framebuffer to remove</dd> </dl> Description Scans all the CRTCs and planes in dev‘s mode_config. If they’re using fb, removes it, setting it to NULL. Then drops the reference to the passed-in framebuffer. Might take the modeset locks. Note that this function optimizes the cleanup away if the caller holds the last reference to the framebuffer. It is also guaranteed to not take the modeset locks in this case. <dl class="function"> <dt id="c.drm_framebuffer_plane_width"> int <code class="descname">drm_framebuffer_plane_width</code>(int width, const struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb, int plane)<a class="headerlink" href="#c.drm_framebuffer_plane_width" title="Permalink to this definition">¶</a></dt> <dd>width of the plane given the first plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">int width</code></dt> <dd>width of the first plane</dd> <dt><code class="docutils literal">const struct drm_framebuffer * fb</code></dt> <dd>the framebuffer</dd> <dt><code class="docutils literal">int plane</code></dt> <dd>plane index</dd> </dl> Return The width of plane, given that the width of the first plane is width. <dl class="function"> <dt id="c.drm_framebuffer_plane_height"> int <code class="descname">drm_framebuffer_plane_height</code>(int height, const struct <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer">drm_framebuffer</a> * fb, int plane)<a class="headerlink" href="#c.drm_framebuffer_plane_height" title="Permalink to this definition">¶</a></dt> <dd>height of the plane given the first plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">int height</code></dt> <dd>height of the first plane</dd> <dt><code class="docutils literal">const struct drm_framebuffer * fb</code></dt> <dd>the framebuffer</dd> <dt><code class="docutils literal">int plane</code></dt> <dd>plane index</dd> </dl> Return The height of plane, given that the height of the first plane is height. </div> </div> <div class="section" id="drm-format-handling"> <h2>DRM Format Handling<a class="headerlink" href="#drm-format-handling" title="Permalink to this headline">¶</a></h2> <dl class="type"> <dt id="c.drm_format_info"> struct <code class="descname">drm_format_info</code><a class="headerlink" href="#c.drm_format_info" title="Permalink to this definition">¶</a></dt> <dd>information about a DRM format </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_format_info { u32 format; u8 depth; u8 num_planes; u8 cpp[3]; u8 hsub; u8 vsub; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">format</code></dt> <dd>4CC format identifier (DRM_FORMAT_*)</dd> <dt><code class="docutils literal">depth</code></dt> <dd>Color depth (number of bits per pixel excluding padding bits), valid for a subset of RGB formats only. This is a legacy field, do not use in new code and set to 0 for new formats.</dd> <dt><code class="docutils literal">num_planes</code></dt> <dd>Number of color planes (1 to 3)</dd> <dt><code class="docutils literal">cpp</code></dt> <dd>Number of bytes per pixel (per plane)</dd> <dt><code class="docutils literal">hsub</code></dt> <dd>Horizontal chroma subsampling factor</dd> <dt><code class="docutils literal">vsub</code></dt> <dd>Vertical chroma subsampling factor</dd> </dl> <dl class="type"> <dt id="c.drm_format_name_buf"> struct <code class="descname">drm_format_name_buf</code><a class="headerlink" href="#c.drm_format_name_buf" title="Permalink to this definition">¶</a></dt> <dd>name of a DRM format </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_format_name_buf { char str[32]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">str</code></dt> <dd>string buffer containing the format name</dd> </dl> <dl class="function"> <dt id="c.drm_mode_legacy_fb_format"> uint32_t <code class="descname">drm_mode_legacy_fb_format</code>(uint32_t bpp, uint32_t depth)<a class="headerlink" href="#c.drm_mode_legacy_fb_format" title="Permalink to this definition">¶</a></dt> <dd>compute drm fourcc code from legacy description </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t bpp</code></dt> <dd>bits per pixels</dd> <dt><code class="docutils literal">uint32_t depth</code></dt> <dd>bit depth per pixel</dd> </dl> Description Computes a drm fourcc pixel format code for the given bpp/depth values. Useful in fbdev emulation code, since that deals in those values. <dl class="function"> <dt id="c.drm_get_format_name"> const char * <code class="descname">drm_get_format_name</code>(uint32_t format, struct <a class="reference internal" href="#c.drm_format_name_buf" title="drm_format_name_buf">drm_format_name_buf</a> * buf)<a class="headerlink" href="#c.drm_get_format_name" title="Permalink to this definition">¶</a></dt> <dd>fill a string with a drm fourcc format’s name </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>format to compute name of</dd> <dt><code class="docutils literal">struct drm_format_name_buf * buf</code></dt> <dd>caller-supplied buffer</dd> </dl> <dl class="function"> <dt> const struct <a class="reference internal" href="#c.drm_format_info" title="drm_format_info">drm_format_info</a> * <code class="descname">drm_format_info</code>(u32 format)</dt> <dd>query information for a given format </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">u32 format</code></dt> <dd>pixel format (DRM_FORMAT_*)</dd> </dl> Description The caller should only pass a supported pixel format to this function. Unsupported pixel formats will generate a warning in the kernel log. Return The instance of struct drm_format_info that describes the pixel format, or NULL if the format is unsupported. <dl class="function"> <dt id="c.drm_get_format_info"> const struct <a class="reference internal" href="#c.drm_format_info" title="drm_format_info">drm_format_info</a> * <code class="descname">drm_get_format_info</code>(struct drm_device * dev, const struct drm_mode_fb_cmd2 * mode_cmd)<a class="headerlink" href="#c.drm_get_format_info" title="Permalink to this definition">¶</a></dt> <dd>query information for a given framebuffer configuration </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">const struct drm_mode_fb_cmd2 * mode_cmd</code></dt> <dd>metadata from the userspace fb creation request</dd> </dl> Return The instance of struct drm_format_info that describes the pixel format, or NULL if the format is unsupported. <dl class="function"> <dt id="c.drm_format_num_planes"> int <code class="descname">drm_format_num_planes</code>(uint32_t format)<a class="headerlink" href="#c.drm_format_num_planes" title="Permalink to this definition">¶</a></dt> <dd>get the number of planes for format </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format (DRM_FORMAT_*)</dd> </dl> Return The number of planes used by the specified pixel format. <dl class="function"> <dt id="c.drm_format_plane_cpp"> int <code class="descname">drm_format_plane_cpp</code>(uint32_t format, int plane)<a class="headerlink" href="#c.drm_format_plane_cpp" title="Permalink to this definition">¶</a></dt> <dd>determine the bytes per pixel value </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format (DRM_FORMAT_*)</dd> <dt><code class="docutils literal">int plane</code></dt> <dd>plane index</dd> </dl> Return The bytes per pixel value for the specified plane. <dl class="function"> <dt id="c.drm_format_horz_chroma_subsampling"> int <code class="descname">drm_format_horz_chroma_subsampling</code>(uint32_t format)<a class="headerlink" href="#c.drm_format_horz_chroma_subsampling" title="Permalink to this definition">¶</a></dt> <dd>get the horizontal chroma subsampling factor </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format (DRM_FORMAT_*)</dd> </dl> Return The horizontal chroma subsampling factor for the specified pixel format. <dl class="function"> <dt id="c.drm_format_vert_chroma_subsampling"> int <code class="descname">drm_format_vert_chroma_subsampling</code>(uint32_t format)<a class="headerlink" href="#c.drm_format_vert_chroma_subsampling" title="Permalink to this definition">¶</a></dt> <dd>get the vertical chroma subsampling factor </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format (DRM_FORMAT_*)</dd> </dl> Return The vertical chroma subsampling factor for the specified pixel format. <dl class="function"> <dt id="c.drm_format_plane_width"> int <code class="descname">drm_format_plane_width</code>(int width, uint32_t format, int plane)<a class="headerlink" href="#c.drm_format_plane_width" title="Permalink to this definition">¶</a></dt> <dd>width of the plane given the first plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">int width</code></dt> <dd>width of the first plane</dd> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format</dd> <dt><code class="docutils literal">int plane</code></dt> <dd>plane index</dd> </dl> Return The width of plane, given that the width of the first plane is width. <dl class="function"> <dt id="c.drm_format_plane_height"> int <code class="descname">drm_format_plane_height</code>(int height, uint32_t format, int plane)<a class="headerlink" href="#c.drm_format_plane_height" title="Permalink to this definition">¶</a></dt> <dd>height of the plane given the first plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">int height</code></dt> <dd>height of the first plane</dd> <dt><code class="docutils literal">uint32_t format</code></dt> <dd>pixel format</dd> <dt><code class="docutils literal">int plane</code></dt> <dd>plane index</dd> </dl> Return The height of plane, given that the height of the first plane is height. </div> <div class="section" id="dumb-buffer-objects"> <h2>Dumb Buffer Objects<a class="headerlink" href="#dumb-buffer-objects" title="Permalink to this headline">¶</a></h2> The KMS API doesn’t standardize backing storage object creation and leaves it to driver-specific ioctls. Furthermore actually creating a buffer object even for GEM-based drivers is done through a driver-specific ioctl - GEM only has a common userspace interface for sharing and destroying objects. While not an issue for full-fledged graphics stacks that include device-specific userspace components (in libdrm for instance), this limit makes DRM-based early boot graphics unnecessarily complex. Dumb objects partly alleviate the problem by providing a standard API to create dumb buffers suitable for scanout, which can then be used to create KMS frame buffers. To support dumb objects drivers must implement the <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.dumb_create</code></a> operation. <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.dumb_destroy</code></a> defaults to <a class="reference internal" href="drm-mm.html#c.drm_gem_dumb_destroy" title="drm_gem_dumb_destroy"><code class="xref c c-func docutils literal">drm_gem_dumb_destroy()</code></a> if not set and <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.dumb_map_offset</code></a> defaults to <a class="reference internal" href="drm-mm.html#c.drm_gem_dumb_map_offset" title="drm_gem_dumb_map_offset"><code class="xref c c-func docutils literal">drm_gem_dumb_map_offset()</code></a>. See the callbacks for further details. Note that dumb objects may not be used for gpu acceleration, as has been attempted on some ARM embedded platforms. Such drivers really must have a hardware-specific ioctl to allocate suitable buffer objects. </div> <div class="section" id="plane-abstraction"> <h2>Plane Abstraction<a class="headerlink" href="#plane-abstraction" title="Permalink to this headline">¶</a></h2> A plane represents an image source that can be blended with or overlayed on top of a CRTC during the scanout process. Planes take their input data from a <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a> object. The plane itself specifies the cropping and scaling of that image, and where it is placed on the visible are of a display pipeline, represented by <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>. A plane can also have additional properties that specify how the pixels are positioned and blended, like rotation or Z-position. All these properties are stored in <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state</code></a>. To create a plane, a KMS drivers allocates and zeroes an instances of <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">struct drm_plane</code></a> (possibly as part of a larger structure) and registers it with a call to <a class="reference internal" href="#c.drm_universal_plane_init" title="drm_universal_plane_init"><code class="xref c c-func docutils literal">drm_universal_plane_init()</code></a>. Cursor and overlay planes are optional. All drivers should provide one primary plane per CRTC to avoid surprising userspace too much. See enum drm_plane_type for a more in-depth discussion of these special uapi-relevant plane types. Special planes are associated with their CRTC by calling <a class="reference internal" href="#c.drm_crtc_init_with_planes" title="drm_crtc_init_with_planes"><code class="xref c c-func docutils literal">drm_crtc_init_with_planes()</code></a>. The type of a plane is exposed in the immutable “type” enumeration property, which has one of the following values: “Overlay”, “Primary”, “Cursor”. <div class="section" id="plane-functions-reference"> <h3>Plane Functions Reference<a class="headerlink" href="#plane-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_plane_state"> struct <code class="descname">drm_plane_state</code><a class="headerlink" href="#c.drm_plane_state" title="Permalink to this definition">¶</a></dt> <dd>mutable plane state </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_plane_state { struct drm_plane *plane; struct drm_crtc *crtc; struct drm_framebuffer *fb; struct dma_fence *fence; int32_t crtc_x; int32_t crtc_y; uint32_t crtc_w, crtc_h; uint32_t src_x, src_y; uint32_t src_h, src_w; unsigned int rotation; unsigned int zpos; unsigned int normalized_zpos; struct drm_rect src, dst; bool visible; struct drm_crtc_commit *commit; struct drm_atomic_state *state; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">plane</code></dt> <dd>backpointer to the plane</dd> <dt><code class="docutils literal">crtc</code></dt> <dd>Currently bound CRTC, NULL if disabled. Do not this write directly, use <a class="reference internal" href="#c.drm_atomic_set_crtc_for_plane" title="drm_atomic_set_crtc_for_plane"><code class="xref c c-func docutils literal">drm_atomic_set_crtc_for_plane()</code></a></dd> <dt><code class="docutils literal">fb</code></dt> <dd>Currently bound framebuffer. Do not write this directly, use <a class="reference internal" href="#c.drm_atomic_set_fb_for_plane" title="drm_atomic_set_fb_for_plane"><code class="xref c c-func docutils literal">drm_atomic_set_fb_for_plane()</code></a></dd> <dt><code class="docutils literal">fence</code></dt> <dd>Optional fence to wait for before scanning out fb. Do not write this directly, use <a class="reference internal" href="#c.drm_atomic_set_fence_for_plane" title="drm_atomic_set_fence_for_plane"><code class="xref c c-func docutils literal">drm_atomic_set_fence_for_plane()</code></a></dd> <dt><code class="docutils literal">crtc_x</code></dt> <dd>Left position of visible portion of plane on crtc, signed dest location allows it to be partially off screen.</dd> <dt><code class="docutils literal">crtc_y</code></dt> <dd>Upper position of visible portion of plane on crtc, signed dest location allows it to be partially off screen.</dd> <dt><code class="docutils literal">crtc_w</code></dt> <dd>width of visible portion of plane on crtc</dd> <dt><code class="docutils literal">crtc_h</code></dt> <dd>height of visible portion of plane on crtc</dd> <dt><code class="docutils literal">src_x</code></dt> <dd>left position of visible portion of plane within plane (in 16.16)</dd> <dt><code class="docutils literal">src_y</code></dt> <dd>upper position of visible portion of plane within plane (in 16.16)</dd> <dt><code class="docutils literal">src_h</code></dt> <dd>height of visible portion of plane (in 16.16)</dd> <dt><code class="docutils literal">src_w</code></dt> <dd>width of visible portion of plane (in 16.16)</dd> <dt><code class="docutils literal">rotation</code></dt> <dd>rotation of the plane</dd> <dt><code class="docutils literal">zpos</code></dt> <dd>priority of the given plane on crtc (optional) Note that multiple active planes on the same crtc can have an identical zpos value. The rule to solving the conflict is to compare the plane object IDs; the plane with a higher ID must be stacked on top of a plane with a lower ID.</dd> <dt><code class="docutils literal">normalized_zpos</code></dt> <dd>normalized value of zpos: unique, range from 0 to N-1 where N is the number of active planes for given crtc. Note that the driver must call <a class="reference internal" href="#c.drm_atomic_normalize_zpos" title="drm_atomic_normalize_zpos"><code class="xref c c-func docutils literal">drm_atomic_normalize_zpos()</code></a> to update this before it can be trusted.</dd> <dt><code class="docutils literal">src</code></dt> <dd>clipped source coordinates of the plane (in 16.16)</dd> <dt><code class="docutils literal">dst</code></dt> <dd>clipped destination coordinates of the plane</dd> <dt><code class="docutils literal">visible</code></dt> <dd>Visibility of the plane. This can be false even if fb!=NULL and crtc!=NULL, due to clipping.</dd> <dt><code class="docutils literal">commit</code></dt> <dd>Tracks the pending commit to prevent use-after-free conditions, and for async plane updates. May be NULL. </dd> <dt><code class="docutils literal">state</code></dt> <dd>backpointer to global drm_atomic_state</dd> </dl> <dl class="type"> <dt id="c.drm_plane_funcs"> struct <code class="descname">drm_plane_funcs</code><a class="headerlink" href="#c.drm_plane_funcs" title="Permalink to this definition">¶</a></dt> <dd>driver plane control functions </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_plane_funcs { int (*update_plane)(struct drm_plane *plane,struct drm_crtc *crtc, struct drm_framebuffer *fb,int crtc_x, int crtc_y,unsigned int crtc_w, unsigned int crtc_h,uint32_t src_x, uint32_t src_y,uint32_t src_w, uint32_t src_h, struct drm_modeset_acquire_ctx *ctx); int (*disable_plane)(struct drm_plane *plane, struct drm_modeset_acquire_ctx *ctx); void (*destroy)(struct drm_plane *plane); void (*reset)(struct drm_plane *plane); int (*set_property)(struct drm_plane *plane, struct drm_property *property, uint64_t val); struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane); void (*atomic_destroy_state)(struct drm_plane *plane, struct drm_plane_state *state); int (*atomic_set_property)(struct drm_plane *plane,struct drm_plane_state *state,struct drm_property *property, uint64_t val); int (*atomic_get_property)(struct drm_plane *plane,const struct drm_plane_state *state,struct drm_property *property, uint64_t *val); int (*late_register)(struct drm_plane *plane); void (*early_unregister)(struct drm_plane *plane); void (*atomic_print_state)(struct drm_printer *p, const struct drm_plane_state *state); bool (*format_mod_supported)(struct drm_plane *plane, uint32_t format, uint64_t modifier); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">update_plane</code></dt> <dd>This is the legacy entry point to enable and configure the plane for the given CRTC and framebuffer. It is never called to disable the plane, i.e. the passed-in crtc and fb paramters are never NULL. The source rectangle in frame buffer memory coordinates is given by the src_x, src_y, src_w and src_h parameters (as 16.16 fixed point values). Devices that don’t support subpixel plane coordinates can ignore the fractional part. The destination rectangle in CRTC coordinates is given by the crtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values). Devices scale the source rectangle to the destination rectangle. If scaling is not supported, and the source rectangle size doesn’t match the destination rectangle size, the driver must return a -<errorname>EINVAL</errorname> error. Drivers implementing atomic modeset should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_update_plane" title="drm_atomic_helper_update_plane"><code class="xref c c-func docutils literal">drm_atomic_helper_update_plane()</code></a> to implement this hook. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">disable_plane</code></dt> <dd>This is the legacy entry point to disable the plane. The DRM core calls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL call with the frame buffer ID set to 0. Disabled planes must not be processed by the CRTC. Drivers implementing atomic modeset should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_disable_plane" title="drm_atomic_helper_disable_plane"><code class="xref c c-func docutils literal">drm_atomic_helper_disable_plane()</code></a> to implement this hook. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">destroy</code></dt> <dd>Clean up plane resources. This is only called at driver unload time through <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a> since a plane cannot be hotplugged in DRM.</dd> <dt><code class="docutils literal">reset</code></dt> <dd>Reset plane hardware and software state to off. This function isn’t called by the core directly, only through <a class="reference internal" href="#c.drm_mode_config_reset" title="drm_mode_config_reset"><code class="xref c c-func docutils literal">drm_mode_config_reset()</code></a>. It’s not a helper hook only for historical reasons. Atomic drivers can use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_plane_reset" title="drm_atomic_helper_plane_reset"><code class="xref c c-func docutils literal">drm_atomic_helper_plane_reset()</code></a> to reset atomic state using this hook. </dd> <dt><code class="docutils literal">set_property</code></dt> <dd>This is the legacy entry point to update a property attached to the plane. This callback is optional if the driver does not support any legacy driver-private properties. For atomic drivers it is not used because property handling is done entirely in the DRM core. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">atomic_duplicate_state</code></dt> <dd>Duplicate the current atomic state for this plane and return it. The core and helpers guarantee that any atomic state duplicated with this hook and still owned by the caller (i.e. not transferred to the driver by calling <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_commit</code></a>) will be cleaned up by calling the atomic_destroy_state hook in this structure. Atomic drivers which don’t subclass <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a> should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_plane_duplicate_state" title="drm_atomic_helper_plane_duplicate_state"><code class="xref c c-func docutils literal">drm_atomic_helper_plane_duplicate_state()</code></a>. Drivers that subclass the state structure to extend it with driver-private state should use <a class="reference internal" href="drm-kms-helpers.html#c.__drm_atomic_helper_plane_duplicate_state" title="__drm_atomic_helper_plane_duplicate_state"><code class="xref c c-func docutils literal">__drm_atomic_helper_plane_duplicate_state()</code></a> to make sure shared state is duplicated in a consistent fashion across drivers. It is an error to call this hook before <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane.state</code></a> has been initialized correctly. NOTE: If the duplicate state references refcounted resources this hook must acquire a reference for each of them. The driver must release these references again in atomic_destroy_state. RETURNS: Duplicated atomic state or NULL when the allocation failed. </dd> <dt><code class="docutils literal">atomic_destroy_state</code></dt> <dd>Destroy a state duplicated with atomic_duplicate_state and release or unreference all resources it references</dd> <dt><code class="docutils literal">atomic_set_property</code></dt> <dd>Decode a driver-private property value and store the decoded value into the passed-in state structure. Since the atomic core decodes all standardized properties (even for extensions beyond the core set of properties which might not be implemented by all drivers) this requires drivers to subclass the state structure. Such driver-private properties should really only be implemented for truly hardware/vendor specific state. Instead it is preferred to standardize atomic extension and decode the properties used to expose such an extension in the core. Do not call this function directly, use <code class="xref c c-func docutils literal">drm_atomic_plane_set_property()</code> instead. This callback is optional if the driver does not support any driver-private atomic properties. NOTE: This function is called in the state assembly phase of atomic modesets, which can be aborted for any reason (including on userspace’s request to just check whether a configuration would be possible). Drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in state parameter. Also since userspace controls in which order properties are set this function must not do any input validation (since the state update is incomplete and hence likely inconsistent). Instead any such input validation must be done in the various atomic_check callbacks. RETURNS: 0 if the property has been found, -EINVAL if the property isn’t implemented by the driver (which shouldn’t ever happen, the core only asks for properties attached to this plane). No other validation is allowed by the driver. The core already checks that the property value is within the range (integer, valid enum value, ...) the driver set when registering the property. </dd> <dt><code class="docutils literal">atomic_get_property</code></dt> <dd>Reads out the decoded driver-private property. This is used to implement the GETPLANE IOCTL. Do not call this function directly, use <code class="xref c c-func docutils literal">drm_atomic_plane_get_property()</code> instead. This callback is optional if the driver does not support any driver-private atomic properties. RETURNS: 0 on success, -EINVAL if the property isn’t implemented by the driver (which should never happen, the core only asks for properties attached to this plane). </dd> <dt><code class="docutils literal">late_register</code></dt> <dd>This optional hook can be used to register additional userspace interfaces attached to the plane like debugfs interfaces. It is called late in the driver load sequence from <a class="reference internal" href="drm-internals.html#c.drm_dev_register" title="drm_dev_register"><code class="xref c c-func docutils literal">drm_dev_register()</code></a>. Everything added from this callback should be unregistered in the early_unregister callback. Returns: 0 on success, or a negative error code on failure. </dd> <dt><code class="docutils literal">early_unregister</code></dt> <dd>This optional hook should be used to unregister the additional userspace interfaces attached to the plane from late_register. It is called from <a class="reference internal" href="drm-internals.html#c.drm_dev_unregister" title="drm_dev_unregister"><code class="xref c c-func docutils literal">drm_dev_unregister()</code></a>, early in the driver unload sequence to disable userspace access before data structures are torndown.</dd> <dt><code class="docutils literal">atomic_print_state</code></dt> <dd>If driver subclasses <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a>, it should implement this optional hook for printing additional driver specific state. Do not call this directly, use <code class="xref c c-func docutils literal">drm_atomic_plane_print_state()</code> instead. </dd> <dt><code class="docutils literal">format_mod_supported</code></dt> <dd>This optional hook is used for the DRM to determine if the given format/modifier combination is valid for the plane. This allows the DRM to generate the correct format bitmask (which formats apply to which modifier). Returns: True if the given modifier is valid for that format on the plane. False otherwise. </dd> </dl> <dl class="type"> <dt id="c.drm_plane_type"> enum <code class="descname">drm_plane_type</code><a class="headerlink" href="#c.drm_plane_type" title="Permalink to this definition">¶</a></dt> <dd>uapi plane type enumeration </dd></dl> Constants <dl class="docutils"> <dt><code class="docutils literal">DRM_PLANE_TYPE_OVERLAY</code></dt> <dd>Overlay planes represent all non-primary, non-cursor planes. Some drivers refer to these types of planes as “sprites” internally.</dd> <dt><code class="docutils literal">DRM_PLANE_TYPE_PRIMARY</code></dt> <dd>Primary planes represent a “main” plane for a CRTC. Primary planes are the planes operated upon by CRTC modesetting and flipping operations described in the <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.page_flip</code></a> and <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.set_config</code></a> hooks.</dd> <dt><code class="docutils literal">DRM_PLANE_TYPE_CURSOR</code></dt> <dd>Cursor planes represent a “cursor” plane for a CRTC. Cursor planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 IOCTLs.</dd> </dl> Description For historical reasons not all planes are made the same. This enumeration is used to tell the different types of planes apart to implement the different uapi semantics for them. For userspace which is universal plane aware and which is using that atomic IOCTL there’s no difference between these planes (beyong what the driver and hardware can support of course). For compatibility with legacy userspace, only overlay planes are made available to userspace by default. Userspace clients may set the DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they wish to receive a universal plane list containing all plane types. See also <a class="reference internal" href="#c.drm_for_each_legacy_plane" title="drm_for_each_legacy_plane"><code class="xref c c-func docutils literal">drm_for_each_legacy_plane()</code></a>. WARNING: The values of this enum is UABI since they’re exposed in the “type” property. <dl class="type"> <dt id="c.drm_plane"> struct <code class="descname">drm_plane</code><a class="headerlink" href="#c.drm_plane" title="Permalink to this definition">¶</a></dt> <dd>central DRM plane control structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_plane { struct drm_device *dev; struct list_head head; char *name; struct drm_modeset_lock mutex; struct drm_mode_object base; uint32_t possible_crtcs; uint32_t *format_types; unsigned int format_count; bool format_default; uint64_t *modifiers; unsigned int modifier_count; struct drm_crtc *crtc; struct drm_framebuffer *fb; struct drm_framebuffer *old_fb; const struct drm_plane_funcs *funcs; struct drm_object_properties properties; enum drm_plane_type type; unsigned index; const struct drm_plane_helper_funcs *helper_private; struct drm_plane_state *state; struct drm_property *zpos_property; struct drm_property *rotation_property; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>DRM device this plane belongs to</dd> <dt><code class="docutils literal">head</code></dt> <dd>for list management</dd> <dt><code class="docutils literal">name</code></dt> <dd>human readable name, can be overwritten by the driver</dd> <dt><code class="docutils literal">mutex</code></dt> <dd>Protects modeset plane state, together with the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc.mutex</code></a> of CRTC this plane is linked to (when active, getting activated or getting disabled). For atomic drivers specifically this protects state. </dd> <dt><code class="docutils literal">base</code></dt> <dd>base mode object</dd> <dt><code class="docutils literal">possible_crtcs</code></dt> <dd>pipes this plane can be bound to</dd> <dt><code class="docutils literal">format_types</code></dt> <dd>array of formats supported by this plane</dd> <dt><code class="docutils literal">format_count</code></dt> <dd>number of formats supported</dd> <dt><code class="docutils literal">format_default</code></dt> <dd>driver hasn’t supplied supported formats for the plane</dd> <dt><code class="docutils literal">modifiers</code></dt> <dd>array of modifiers supported by this plane</dd> <dt><code class="docutils literal">modifier_count</code></dt> <dd>number of modifiers supported</dd> <dt><code class="docutils literal">crtc</code></dt> <dd>Currently bound CRTC, only really meaningful for non-atomic drivers. Atomic drivers should instead check <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state.crtc</code></a>.</dd> <dt><code class="docutils literal">fb</code></dt> <dd>Currently bound framebuffer, only really meaningful for non-atomic drivers. Atomic drivers should instead check <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state.fb</code></a>.</dd> <dt><code class="docutils literal">old_fb</code></dt> <dd>Temporary tracking of the old fb while a modeset is ongoing. Used by <a class="reference internal" href="#c.drm_mode_set_config_internal" title="drm_mode_set_config_internal"><code class="xref c c-func docutils literal">drm_mode_set_config_internal()</code></a> to implement correct refcounting.</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>helper functions</dd> <dt><code class="docutils literal">properties</code></dt> <dd>property tracking for this plane</dd> <dt><code class="docutils literal">type</code></dt> <dd>type of plane (overlay, primary, cursor)</dd> <dt><code class="docutils literal">index</code></dt> <dd>Position inside the mode_config.list, can be used as an array index. It is invariant over the lifetime of the plane.</dd> <dt><code class="docutils literal">helper_private</code></dt> <dd>mid-layer private data</dd> <dt><code class="docutils literal">state</code></dt> <dd>Current atomic state for this plane. This is protected by mutex. Note that nonblocking atomic commits access the current plane state without taking locks. Either by going through the <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointers, see <a class="reference internal" href="#c.for_each_oldnew_plane_in_state" title="for_each_oldnew_plane_in_state"><code class="xref c c-func docutils literal">for_each_oldnew_plane_in_state()</code></a>, <a class="reference internal" href="#c.for_each_old_plane_in_state" title="for_each_old_plane_in_state"><code class="xref c c-func docutils literal">for_each_old_plane_in_state()</code></a> and <a class="reference internal" href="#c.for_each_new_plane_in_state" title="for_each_new_plane_in_state"><code class="xref c c-func docutils literal">for_each_new_plane_in_state()</code></a>. Or through careful ordering of atomic commit operations as implemented in the atomic helpers, see <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit"><code class="xref c c-type docutils literal">struct drm_crtc_commit</code></a>. </dd> <dt><code class="docutils literal">zpos_property</code></dt> <dd>zpos property for this plane</dd> <dt><code class="docutils literal">rotation_property</code></dt> <dd>rotation property for this plane</dd> </dl> <dl class="function"> <dt id="c.drm_plane_index"> unsigned int <code class="descname">drm_plane_index</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_plane_index" title="Permalink to this definition">¶</a></dt> <dd>find the index of a registered plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to find index for</dd> </dl> Description Given a registered plane, return the index of that plane within a DRM device’s list of planes. <dl class="function"> <dt id="c.drm_plane_find"> struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * <code class="descname">drm_plane_find</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_plane_find" title="Permalink to this definition">¶</a></dt> <dd>find a <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>plane id</dd> </dl> Description Returns the plane with id, NULL if it doesn’t exist. Simple wrapper around <a class="reference internal" href="#c.drm_mode_object_find" title="drm_mode_object_find"><code class="xref c c-func docutils literal">drm_mode_object_find()</code></a>. <dl class="function"> <dt id="c.drm_for_each_plane_mask"> <code class="descname">drm_for_each_plane_mask</code>(plane, dev, plane_mask)<a class="headerlink" href="#c.drm_for_each_plane_mask" title="Permalink to this definition">¶</a></dt> <dd>iterate over planes specified by bitmask </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">plane</code></dt> <dd>the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the DRM device</dd> <dt><code class="docutils literal">plane_mask</code></dt> <dd>bitmask of plane indices</dd> </dl> Description Iterate over all planes specified by bitmask. <dl class="function"> <dt id="c.drm_for_each_legacy_plane"> <code class="descname">drm_for_each_legacy_plane</code>(plane, dev)<a class="headerlink" href="#c.drm_for_each_legacy_plane" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes for legacy userspace </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">plane</code></dt> <dd>the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the DRM device</dd> </dl> Description Iterate over all legacy planes of dev, excluding primary and cursor planes. This is useful for implementing userspace apis when userspace is not universal plane aware. See also <a class="reference internal" href="#c.drm_plane_type" title="drm_plane_type"><code class="xref c c-type docutils literal">enum drm_plane_type</code></a>. <dl class="function"> <dt id="c.drm_for_each_plane"> <code class="descname">drm_for_each_plane</code>(plane, dev)<a class="headerlink" href="#c.drm_for_each_plane" title="Permalink to this definition">¶</a></dt> <dd>iterate over all planes </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">plane</code></dt> <dd>the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the DRM device</dd> </dl> Description Iterate over all planes of dev, include primary and cursor planes. <dl class="function"> <dt id="c.drm_universal_plane_init"> int <code class="descname">drm_universal_plane_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, uint32_t possible_crtcs, const struct <a class="reference internal" href="#c.drm_plane_funcs" title="drm_plane_funcs">drm_plane_funcs</a> * funcs, const uint32_t * formats, unsigned int format_count, const uint64_t * format_modifiers, enum <a class="reference internal" href="#c.drm_plane_type" title="drm_plane_type">drm_plane_type</a> type, const char * name, ...)<a class="headerlink" href="#c.drm_universal_plane_init" title="Permalink to this definition">¶</a></dt> <dd>Initialize a new universal plane object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane object to init</dd> <dt><code class="docutils literal">uint32_t possible_crtcs</code></dt> <dd>bitmask of possible CRTCs</dd> <dt><code class="docutils literal">const struct drm_plane_funcs * funcs</code></dt> <dd>callbacks for the new plane</dd> <dt><code class="docutils literal">const uint32_t * formats</code></dt> <dd>array of supported formats (DRM_FORMAT_*)</dd> <dt><code class="docutils literal">unsigned int format_count</code></dt> <dd>number of elements in formats</dd> <dt><code class="docutils literal">const uint64_t * format_modifiers</code></dt> <dd>array of struct drm_format modifiers terminated by DRM_FORMAT_MOD_INVALID</dd> <dt><code class="docutils literal">enum drm_plane_type type</code></dt> <dd>type of plane (overlay, primary, cursor)</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>printf style format string for the plane name, or NULL for default name</dd> <dt><code class="docutils literal">...</code></dt> <dd>variable arguments</dd> </dl> Description Initializes a plane object of type type. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_plane_init"> int <code class="descname">drm_plane_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, uint32_t possible_crtcs, const struct <a class="reference internal" href="#c.drm_plane_funcs" title="drm_plane_funcs">drm_plane_funcs</a> * funcs, const uint32_t * formats, unsigned int format_count, bool is_primary)<a class="headerlink" href="#c.drm_plane_init" title="Permalink to this definition">¶</a></dt> <dd>Initialize a legacy plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane object to init</dd> <dt><code class="docutils literal">uint32_t possible_crtcs</code></dt> <dd>bitmask of possible CRTCs</dd> <dt><code class="docutils literal">const struct drm_plane_funcs * funcs</code></dt> <dd>callbacks for the new plane</dd> <dt><code class="docutils literal">const uint32_t * formats</code></dt> <dd>array of supported formats (DRM_FORMAT_*)</dd> <dt><code class="docutils literal">unsigned int format_count</code></dt> <dd>number of elements in formats</dd> <dt><code class="docutils literal">bool is_primary</code></dt> <dd>plane type (primary vs overlay)</dd> </dl> Description Legacy API to initialize a DRM plane. New drivers should call <a class="reference internal" href="#c.drm_universal_plane_init" title="drm_universal_plane_init"><code class="xref c c-func docutils literal">drm_universal_plane_init()</code></a> instead. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_plane_cleanup"> void <code class="descname">drm_plane_cleanup</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_plane_cleanup" title="Permalink to this definition">¶</a></dt> <dd>Clean up the core plane usage </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to cleanup</dd> </dl> Description This function cleans up plane and removes it from the DRM mode setting core. Note that the function does not free the plane structure itself, this is the responsibility of the caller. <dl class="function"> <dt id="c.drm_plane_from_index"> struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * <code class="descname">drm_plane_from_index</code>(struct drm_device * dev, int idx)<a class="headerlink" href="#c.drm_plane_from_index" title="Permalink to this definition">¶</a></dt> <dd>find the registered plane at an index </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">int idx</code></dt> <dd>index of registered plane to find for</dd> </dl> Description Given a plane index, return the registered plane from DRM device’s list of planes with matching index. This is the inverse of <a class="reference internal" href="#c.drm_plane_index" title="drm_plane_index"><code class="xref c c-func docutils literal">drm_plane_index()</code></a>. <dl class="function"> <dt id="c.drm_plane_force_disable"> void <code class="descname">drm_plane_force_disable</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane)<a class="headerlink" href="#c.drm_plane_force_disable" title="Permalink to this definition">¶</a></dt> <dd>Forcibly disable a plane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>plane to disable</dd> </dl> Description Forces the plane to be disabled. Used when the plane’s current framebuffer is destroyed, and when restoring fbdev mode. Note that this function is not suitable for atomic drivers, since it doesn’t wire through the lock acquisition context properly and hence can’t handle retries or driver private locks. You probably want to use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_disable_plane" title="drm_atomic_helper_disable_plane"><code class="xref c c-func docutils literal">drm_atomic_helper_disable_plane()</code></a> or <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_disable_planes_on_crtc" title="drm_atomic_helper_disable_planes_on_crtc"><code class="xref c c-func docutils literal">drm_atomic_helper_disable_planes_on_crtc()</code></a> instead. <dl class="function"> <dt id="c.drm_mode_plane_set_obj_prop"> int <code class="descname">drm_mode_plane_set_obj_prop</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint64_t value)<a class="headerlink" href="#c.drm_mode_plane_set_obj_prop" title="Permalink to this definition">¶</a></dt> <dd>set the value of a property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>drm plane object to set property value for</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to set</dd> <dt><code class="docutils literal">uint64_t value</code></dt> <dd>value the property should be set to</dd> </dl> Description This functions sets a given property on a given plane object. This function calls the driver’s ->set_property callback and changes the software state of the property if the callback succeeds. Return Zero on success, error code on failure. </div> </div> <div class="section" id="display-modes-function-reference"> <h2>Display Modes Function Reference<a class="headerlink" href="#display-modes-function-reference" title="Permalink to this headline">¶</a></h2> <dl class="type"> <dt id="c.drm_mode_status"> enum <code class="descname">drm_mode_status</code><a class="headerlink" href="#c.drm_mode_status" title="Permalink to this definition">¶</a></dt> <dd>hardware support status of a mode </dd></dl> Constants <dl class="docutils"> <dt><code class="docutils literal">MODE_OK</code></dt> <dd>Mode OK</dd> <dt><code class="docutils literal">MODE_HSYNC</code></dt> <dd>hsync out of range</dd> <dt><code class="docutils literal">MODE_VSYNC</code></dt> <dd>vsync out of range</dd> <dt><code class="docutils literal">MODE_H_ILLEGAL</code></dt> <dd>mode has illegal horizontal timings</dd> <dt><code class="docutils literal">MODE_V_ILLEGAL</code></dt> <dd>mode has illegal horizontal timings</dd> <dt><code class="docutils literal">MODE_BAD_WIDTH</code></dt> <dd>requires an unsupported linepitch</dd> <dt><code class="docutils literal">MODE_NOMODE</code></dt> <dd>no mode with a matching name</dd> <dt><code class="docutils literal">MODE_NO_INTERLACE</code></dt> <dd>interlaced mode not supported</dd> <dt><code class="docutils literal">MODE_NO_DBLESCAN</code></dt> <dd>doublescan mode not supported</dd> <dt><code class="docutils literal">MODE_NO_VSCAN</code></dt> <dd>multiscan mode not supported</dd> <dt><code class="docutils literal">MODE_MEM</code></dt> <dd>insufficient video memory</dd> <dt><code class="docutils literal">MODE_VIRTUAL_X</code></dt> <dd>mode width too large for specified virtual size</dd> <dt><code class="docutils literal">MODE_VIRTUAL_Y</code></dt> <dd>mode height too large for specified virtual size</dd> <dt><code class="docutils literal">MODE_MEM_VIRT</code></dt> <dd>insufficient video memory given virtual size</dd> <dt><code class="docutils literal">MODE_NOCLOCK</code></dt> <dd>no fixed clock available</dd> <dt><code class="docutils literal">MODE_CLOCK_HIGH</code></dt> <dd>clock required is too high</dd> <dt><code class="docutils literal">MODE_CLOCK_LOW</code></dt> <dd>clock required is too low</dd> <dt><code class="docutils literal">MODE_CLOCK_RANGE</code></dt> <dd>clock/mode isn’t in a ClockRange</dd> <dt><code class="docutils literal">MODE_BAD_HVALUE</code></dt> <dd>horizontal timing was out of range</dd> <dt><code class="docutils literal">MODE_BAD_VVALUE</code></dt> <dd>vertical timing was out of range</dd> <dt><code class="docutils literal">MODE_BAD_VSCAN</code></dt> <dd>VScan value out of range</dd> <dt><code class="docutils literal">MODE_HSYNC_NARROW</code></dt> <dd>horizontal sync too narrow</dd> <dt><code class="docutils literal">MODE_HSYNC_WIDE</code></dt> <dd>horizontal sync too wide</dd> <dt><code class="docutils literal">MODE_HBLANK_NARROW</code></dt> <dd>horizontal blanking too narrow</dd> <dt><code class="docutils literal">MODE_HBLANK_WIDE</code></dt> <dd>horizontal blanking too wide</dd> <dt><code class="docutils literal">MODE_VSYNC_NARROW</code></dt> <dd>vertical sync too narrow</dd> <dt><code class="docutils literal">MODE_VSYNC_WIDE</code></dt> <dd>vertical sync too wide</dd> <dt><code class="docutils literal">MODE_VBLANK_NARROW</code></dt> <dd>vertical blanking too narrow</dd> <dt><code class="docutils literal">MODE_VBLANK_WIDE</code></dt> <dd>vertical blanking too wide</dd> <dt><code class="docutils literal">MODE_PANEL</code></dt> <dd>exceeds panel dimensions</dd> <dt><code class="docutils literal">MODE_INTERLACE_WIDTH</code></dt> <dd>width too large for interlaced mode</dd> <dt><code class="docutils literal">MODE_ONE_WIDTH</code></dt> <dd>only one width is supported</dd> <dt><code class="docutils literal">MODE_ONE_HEIGHT</code></dt> <dd>only one height is supported</dd> <dt><code class="docutils literal">MODE_ONE_SIZE</code></dt> <dd>only one resolution is supported</dd> <dt><code class="docutils literal">MODE_NO_REDUCED</code></dt> <dd>monitor doesn’t accept reduced blanking</dd> <dt><code class="docutils literal">MODE_NO_STEREO</code></dt> <dd>stereo modes not supported</dd> <dt><code class="docutils literal">MODE_NO_420</code></dt> <dd>ycbcr 420 modes not supported</dd> <dt><code class="docutils literal">MODE_STALE</code></dt> <dd>mode has become stale</dd> <dt><code class="docutils literal">MODE_BAD</code></dt> <dd>unspecified reason</dd> <dt><code class="docutils literal">MODE_ERROR</code></dt> <dd>error condition</dd> </dl> Description This enum is used to filter out modes not supported by the driver/hardware combination. <dl class="type"> <dt id="c.drm_display_mode"> struct <code class="descname">drm_display_mode</code><a class="headerlink" href="#c.drm_display_mode" title="Permalink to this definition">¶</a></dt> <dd>DRM kernel-internal display mode structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_display_mode { struct list_head head; struct drm_mode_object base; char name[DRM_DISPLAY_MODE_LEN]; enum drm_mode_status status; unsigned int type; int clock; int hdisplay; int hsync_start; int hsync_end; int htotal; int hskew; int vdisplay; int vsync_start; int vsync_end; int vtotal; int vscan; unsigned int flags; int width_mm; int height_mm; int crtc_clock; int crtc_hdisplay; int crtc_hblank_start; int crtc_hblank_end; int crtc_hsync_start; int crtc_hsync_end; int crtc_htotal; int crtc_hskew; int crtc_vdisplay; int crtc_vblank_start; int crtc_vblank_end; int crtc_vsync_start; int crtc_vsync_end; int crtc_vtotal; int *private; int private_flags; int vrefresh; int hsync; enum hdmi_picture_aspect picture_aspect_ratio; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">head</code></dt> <dd>struct list_head for mode lists.</dd> <dt><code class="docutils literal">base</code></dt> <dd>A display mode is a normal modeset object, possibly including public userspace id. FIXME: This can probably be removed since the entire concept of userspace managing modes explicitly has never landed in upstream kernel mode setting support. </dd> <dt><code class="docutils literal">name</code></dt> <dd>Human-readable name of the mode, filled out with <a class="reference internal" href="#c.drm_mode_set_name" title="drm_mode_set_name"><code class="xref c c-func docutils literal">drm_mode_set_name()</code></a>.</dd> <dt><code class="docutils literal">status</code></dt> <dd>Status of the mode, used to filter out modes not supported by the hardware. See enum <a class="reference internal" href="#c.drm_mode_status" title="drm_mode_status"><code class="xref c c-type docutils literal">drm_mode_status</code></a>.</dd> <dt><code class="docutils literal">type</code></dt> <dd>A bitmask of flags, mostly about the source of a mode. Possible flags are: <blockquote> <div><ul class="simple"> <li>DRM_MODE_TYPE_BUILTIN: Meant for hard-coded modes, effectively unused.</li> <li>DRM_MODE_TYPE_PREFERRED: Preferred mode, usually the native resolution of an LCD panel. There should only be one preferred mode per connector at any given time.</li> <li>DRM_MODE_TYPE_DRIVER: Mode created by the driver, which is all of them really. Drivers must set this bit for all modes they create and expose to userspace.</li> </ul> </div></blockquote> Plus a big list of flags which shouldn’t be used at all, but are still around since these flags are also used in the userspace ABI: <blockquote class="last"> <div><ul class="simple"> <li>DRM_MODE_TYPE_DEFAULT: Again a leftover, use DRM_MODE_TYPE_PREFERRED instead.</li> <li>DRM_MODE_TYPE_CLOCK_C and DRM_MODE_TYPE_CRTC_C: Define leftovers which are stuck around for hysterical raisins only. No one has an idea what they were meant for. Don’t use.</li> <li>DRM_MODE_TYPE_USERDEF: Mode defined by userspace, again a vestige from older kms designs where userspace had to first add a custom mode to the kernel’s mode list before it could use it. Don’t use.</li> </ul> </div></blockquote> </dd> <dt><code class="docutils literal">clock</code></dt> <dd>Pixel clock in kHz.</dd> <dt><code class="docutils literal">hdisplay</code></dt> <dd>horizontal display size</dd> <dt><code class="docutils literal">hsync_start</code></dt> <dd>horizontal sync start</dd> <dt><code class="docutils literal">hsync_end</code></dt> <dd>horizontal sync end</dd> <dt><code class="docutils literal">htotal</code></dt> <dd>horizontal total size</dd> <dt><code class="docutils literal">hskew</code></dt> <dd>horizontal skew?!</dd> <dt><code class="docutils literal">vdisplay</code></dt> <dd>vertical display size</dd> <dt><code class="docutils literal">vsync_start</code></dt> <dd>vertical sync start</dd> <dt><code class="docutils literal">vsync_end</code></dt> <dd>vertical sync end</dd> <dt><code class="docutils literal">vtotal</code></dt> <dd>vertical total size</dd> <dt><code class="docutils literal">vscan</code></dt> <dd>vertical scan?!</dd> <dt><code class="docutils literal">flags</code></dt> <dd>Sync and timing flags: <blockquote> <div><ul class="simple"> <li>DRM_MODE_FLAG_PHSYNC: horizontal sync is active high.</li> <li>DRM_MODE_FLAG_NHSYNC: horizontal sync is active low.</li> <li>DRM_MODE_FLAG_PVSYNC: vertical sync is active high.</li> <li>DRM_MODE_FLAG_NVSYNC: vertical sync is active low.</li> <li>DRM_MODE_FLAG_INTERLACE: mode is interlaced.</li> <li>DRM_MODE_FLAG_DBLSCAN: mode uses doublescan.</li> <li>DRM_MODE_FLAG_CSYNC: mode uses composite sync.</li> <li>DRM_MODE_FLAG_PCSYNC: composite sync is active high.</li> <li>DRM_MODE_FLAG_NCSYNC: composite sync is active low.</li> <li>DRM_MODE_FLAG_HSKEW: hskew provided (not used?).</li> <li>DRM_MODE_FLAG_BCAST: not used?</li> <li>DRM_MODE_FLAG_PIXMUX: not used?</li> <li>DRM_MODE_FLAG_DBLCLK: double-clocked mode.</li> <li>DRM_MODE_FLAG_CLKDIV2: half-clocked mode.</li> </ul> </div></blockquote> Additionally there’s flags to specify how 3D modes are packed: <blockquote class="last"> <div><ul class="simple"> <li>DRM_MODE_FLAG_3D_NONE: normal, non-3D mode.</li> <li>DRM_MODE_FLAG_3D_FRAME_PACKING: 2 full frames for left and right.</li> <li>DRM_MODE_FLAG_3D_FIELD_ALTERNATIVE: interleaved like fields.</li> <li>DRM_MODE_FLAG_3D_LINE_ALTERNATIVE: interleaved lines.</li> <li>DRM_MODE_FLAG_3D_SIDE_BY_SIDE_FULL: side-by-side full frames.</li> <li>DRM_MODE_FLAG_3D_L_DEPTH: ?</li> <li>DRM_MODE_FLAG_3D_L_DEPTH_GFX_GFX_DEPTH: ?</li> <li>DRM_MODE_FLAG_3D_TOP_AND_BOTTOM: frame split into top and bottom parts.</li> <li>DRM_MODE_FLAG_3D_SIDE_BY_SIDE_HALF: frame split into left and right parts.</li> </ul> </div></blockquote> </dd> <dt><code class="docutils literal">width_mm</code></dt> <dd>Addressable size of the output in mm, projectors should set this to 0.</dd> <dt><code class="docutils literal">height_mm</code></dt> <dd>Addressable size of the output in mm, projectors should set this to 0.</dd> <dt><code class="docutils literal">crtc_clock</code></dt> <dd>Actual pixel or dot clock in the hardware. This differs from the logical clock when e.g. using interlacing, double-clocking, stereo modes or other fancy stuff that changes the timings and signals actually sent over the wire. This is again in kHz. Note that with digital outputs like HDMI or DP there’s usually a massive confusion between the dot clock and the signal clock at the bit encoding level. Especially when a 8b/10b encoding is used and the difference is exactly a factor of 10. </dd> <dt><code class="docutils literal">crtc_hdisplay</code></dt> <dd>hardware mode horizontal display size</dd> <dt><code class="docutils literal">crtc_hblank_start</code></dt> <dd>hardware mode horizontal blank start</dd> <dt><code class="docutils literal">crtc_hblank_end</code></dt> <dd>hardware mode horizontal blank end</dd> <dt><code class="docutils literal">crtc_hsync_start</code></dt> <dd>hardware mode horizontal sync start</dd> <dt><code class="docutils literal">crtc_hsync_end</code></dt> <dd>hardware mode horizontal sync end</dd> <dt><code class="docutils literal">crtc_htotal</code></dt> <dd>hardware mode horizontal total size</dd> <dt><code class="docutils literal">crtc_hskew</code></dt> <dd>hardware mode horizontal skew?!</dd> <dt><code class="docutils literal">crtc_vdisplay</code></dt> <dd>hardware mode vertical display size</dd> <dt><code class="docutils literal">crtc_vblank_start</code></dt> <dd>hardware mode vertical blank start</dd> <dt><code class="docutils literal">crtc_vblank_end</code></dt> <dd>hardware mode vertical blank end</dd> <dt><code class="docutils literal">crtc_vsync_start</code></dt> <dd>hardware mode vertical sync start</dd> <dt><code class="docutils literal">crtc_vsync_end</code></dt> <dd>hardware mode vertical sync end</dd> <dt><code class="docutils literal">crtc_vtotal</code></dt> <dd>hardware mode vertical total size</dd> <dt><code class="docutils literal">private</code></dt> <dd>Pointer for driver private data. This can only be used for mode objects passed to drivers in modeset operations. It shouldn’t be used by atomic drivers since they can store any additional data by subclassing state structures.</dd> <dt><code class="docutils literal">private_flags</code></dt> <dd>Similar to private, but just an integer.</dd> <dt><code class="docutils literal">vrefresh</code></dt> <dd>Vertical refresh rate, for debug output in human readable form. Not used in a functional way. This value is in Hz. </dd> <dt><code class="docutils literal">hsync</code></dt> <dd>Horizontal refresh rate, for debug output in human readable form. Not used in a functional way. This value is in kHz. </dd> <dt><code class="docutils literal">picture_aspect_ratio</code></dt> <dd>Field for setting the HDMI picture aspect ratio of a mode.</dd> </dl> Description The horizontal and vertical timings are defined per the following diagram. <div class="highlight-none"><div class="highlight"><pre> Active Front Sync Back Region Porch Porch <-----------------------><----------------><-------------><--------------> //////////////////////| ////////////////////// | ////////////////////// |.................. ................ _______________ <----- [hv]display -----> <------------- [hv]sync_start ------------> <--------------------- [hv]sync_end ---------------------> <-------------------------------- [hv]total ----------------------------->* </pre></div> </div> This structure contains two copies of timings. First are the plain timings, which specify the logical mode, as it would be for a progressive 1:1 scanout at the refresh rate userspace can observe through vblank timestamps. Then there’s the hardware timings, which are corrected for interlacing, double-clocking and similar things. They are provided as a convenience, and can be appropriately computed using <a class="reference internal" href="#c.drm_mode_set_crtcinfo" title="drm_mode_set_crtcinfo"><code class="xref c c-func docutils literal">drm_mode_set_crtcinfo()</code></a>. For printing you can use <code class="docutils literal">DRM_MODE_FMT</code> and <a class="reference internal" href="#c.DRM_MODE_ARG" title="DRM_MODE_ARG"><code class="xref c c-func docutils literal">DRM_MODE_ARG()</code></a>. <dl class="function"> <dt id="c.DRM_MODE_FMT"> <code class="descname">DRM_MODE_FMT</code>()<a class="headerlink" href="#c.DRM_MODE_FMT" title="Permalink to this definition">¶</a></dt> <dd>printf string for <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode"><code class="xref c c-type docutils literal">struct drm_display_mode</code></a> </dd></dl> Parameters <dl class="function"> <dt id="c.DRM_MODE_ARG"> <code class="descname">DRM_MODE_ARG</code>(m)<a class="headerlink" href="#c.DRM_MODE_ARG" title="Permalink to this definition">¶</a></dt> <dd>printf arguments for <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode"><code class="xref c c-type docutils literal">struct drm_display_mode</code></a> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">m</code></dt> <dd>display mode</dd> </dl> <dl class="function"> <dt id="c.drm_mode_is_stereo"> bool <code class="descname">drm_mode_is_stereo</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_is_stereo" title="Permalink to this definition">¶</a></dt> <dd>check for stereo mode flags </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>drm_display_mode to check</dd> </dl> Return True if the mode is one of the stereo modes (like side-by-side), false if not. <dl class="function"> <dt id="c.drm_mode_debug_printmodeline"> void <code class="descname">drm_mode_debug_printmodeline</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_debug_printmodeline" title="Permalink to this definition">¶</a></dt> <dd>print a mode to dmesg </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to print</dd> </dl> Description Describe mode using DRM_DEBUG. <dl class="function"> <dt id="c.drm_mode_create"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_mode_create</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_create" title="Permalink to this definition">¶</a></dt> <dd>create a new display mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Create a new, cleared drm_display_mode with kzalloc, allocate an ID for it and return it. Return Pointer to new mode on success, NULL on error. <dl class="function"> <dt id="c.drm_mode_destroy"> void <code class="descname">drm_mode_destroy</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_destroy" title="Permalink to this definition">¶</a></dt> <dd>remove a mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_display_mode * mode</code></dt> <dd>mode to remove</dd> </dl> Description Release mode‘s unique ID, then free it mode structure itself using kfree. <dl class="function"> <dt id="c.drm_mode_probed_add"> void <code class="descname">drm_mode_probed_add</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_probed_add" title="Permalink to this definition">¶</a></dt> <dd>add a mode to a connector’s probed_mode list </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector the new mode</dd> <dt><code class="docutils literal">struct drm_display_mode * mode</code></dt> <dd>mode data</dd> </dl> Description Add mode to connector‘s probed_mode list for later use. This list should then in a second step get filtered and all the modes actually supported by the hardware moved to the connector‘s modes list. <dl class="function"> <dt id="c.drm_cvt_mode"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_cvt_mode</code>(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool reduced, bool interlaced, bool margins)<a class="headerlink" href="#c.drm_cvt_mode" title="Permalink to this definition">¶</a></dt> <dd>create a modeline based on the CVT algorithm </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int hdisplay</code></dt> <dd>hdisplay size</dd> <dt><code class="docutils literal">int vdisplay</code></dt> <dd>vdisplay size</dd> <dt><code class="docutils literal">int vrefresh</code></dt> <dd>vrefresh rate</dd> <dt><code class="docutils literal">bool reduced</code></dt> <dd>whether to use reduced blanking</dd> <dt><code class="docutils literal">bool interlaced</code></dt> <dd>whether to compute an interlaced mode</dd> <dt><code class="docutils literal">bool margins</code></dt> <dd>whether to add margins (borders)</dd> </dl> Description This function is called to generate the modeline based on CVT algorithm according to the hdisplay, vdisplay, vrefresh. It is based from the VESA(TM) Coordinated Video Timing Generator by Graham Loveridge April 9, 2003 available at <a class="reference external" href="http://www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls">http://www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls</a> And it is copied from xf86CVTmode in xserver/hw/xfree86/modes/xf86cvt.c. What I have done is to translate it by using integer calculation. Return The modeline based on the CVT algorithm stored in a drm_display_mode object. The display mode object is allocated with <a class="reference internal" href="#c.drm_mode_create" title="drm_mode_create"><code class="xref c c-func docutils literal">drm_mode_create()</code></a>. Returns NULL when no mode could be allocated. <dl class="function"> <dt id="c.drm_gtf_mode_complex"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_gtf_mode_complex</code>(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins, int GTF_M, int GTF_2C, int GTF_K, int GTF_2J)<a class="headerlink" href="#c.drm_gtf_mode_complex" title="Permalink to this definition">¶</a></dt> <dd>create the modeline based on the full GTF algorithm </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int hdisplay</code></dt> <dd>hdisplay size</dd> <dt><code class="docutils literal">int vdisplay</code></dt> <dd>vdisplay size</dd> <dt><code class="docutils literal">int vrefresh</code></dt> <dd>vrefresh rate.</dd> <dt><code class="docutils literal">bool interlaced</code></dt> <dd>whether to compute an interlaced mode</dd> <dt><code class="docutils literal">int margins</code></dt> <dd>desired margin (borders) size</dd> <dt><code class="docutils literal">int GTF_M</code></dt> <dd>extended GTF formula parameters</dd> <dt><code class="docutils literal">int GTF_2C</code></dt> <dd>extended GTF formula parameters</dd> <dt><code class="docutils literal">int GTF_K</code></dt> <dd>extended GTF formula parameters</dd> <dt><code class="docutils literal">int GTF_2J</code></dt> <dd>extended GTF formula parameters</dd> </dl> Description GTF feature blocks specify C and J in multiples of 0.5, so we pass them in here multiplied by two. For a C of 40, pass in 80. Return The modeline based on the full GTF algorithm stored in a drm_display_mode object. The display mode object is allocated with <a class="reference internal" href="#c.drm_mode_create" title="drm_mode_create"><code class="xref c c-func docutils literal">drm_mode_create()</code></a>. Returns NULL when no mode could be allocated. <dl class="function"> <dt id="c.drm_gtf_mode"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_gtf_mode</code>(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins)<a class="headerlink" href="#c.drm_gtf_mode" title="Permalink to this definition">¶</a></dt> <dd>create the modeline based on the GTF algorithm </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int hdisplay</code></dt> <dd>hdisplay size</dd> <dt><code class="docutils literal">int vdisplay</code></dt> <dd>vdisplay size</dd> <dt><code class="docutils literal">int vrefresh</code></dt> <dd>vrefresh rate.</dd> <dt><code class="docutils literal">bool interlaced</code></dt> <dd>whether to compute an interlaced mode</dd> <dt><code class="docutils literal">int margins</code></dt> <dd>desired margin (borders) size</dd> </dl> Description return the modeline based on GTF algorithm This function is to create the modeline based on the GTF algorithm. Generalized Timing Formula is derived from: <blockquote> <div>GTF Spreadsheet by Andy Morrish (1/5/97) available at <a class="reference external" href="http://www.vesa.org">http://www.vesa.org</a></div></blockquote> And it is copied from the file of xserver/hw/xfree86/modes/xf86gtf.c. What I have done is to translate it by using integer calculation. I also refer to the function of fb_get_mode in the file of drivers/video/fbmon.c Standard GTF parameters: <div class="highlight-none"><div class="highlight"><pre>M = 600 C = 40 K = 128 J = 20 </pre></div> </div> Return The modeline based on the GTF algorithm stored in a drm_display_mode object. The display mode object is allocated with <a class="reference internal" href="#c.drm_mode_create" title="drm_mode_create"><code class="xref c c-func docutils literal">drm_mode_create()</code></a>. Returns NULL when no mode could be allocated. <dl class="function"> <dt id="c.drm_display_mode_from_videomode"> void <code class="descname">drm_display_mode_from_videomode</code>(const struct videomode * vm, struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * dmode)<a class="headerlink" href="#c.drm_display_mode_from_videomode" title="Permalink to this definition">¶</a></dt> <dd>fill in dmode using vm, </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct videomode * vm</code></dt> <dd>videomode structure to use as source</dd> <dt><code class="docutils literal">struct drm_display_mode * dmode</code></dt> <dd>drm_display_mode structure to use as destination</dd> </dl> Description Fills out dmode using the display mode specified in vm. <dl class="function"> <dt id="c.drm_display_mode_to_videomode"> void <code class="descname">drm_display_mode_to_videomode</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * dmode, struct videomode * vm)<a class="headerlink" href="#c.drm_display_mode_to_videomode" title="Permalink to this definition">¶</a></dt> <dd>fill in vm using dmode, </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * dmode</code></dt> <dd>drm_display_mode structure to use as source</dd> <dt><code class="docutils literal">struct videomode * vm</code></dt> <dd>videomode structure to use as destination</dd> </dl> Description Fills out vm using the display mode specified in dmode. <dl class="function"> <dt id="c.drm_bus_flags_from_videomode"> void <code class="descname">drm_bus_flags_from_videomode</code>(const struct videomode * vm, u32 * bus_flags)<a class="headerlink" href="#c.drm_bus_flags_from_videomode" title="Permalink to this definition">¶</a></dt> <dd>extract information about pixelclk and DE polarity from videomode and store it in a separate variable </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct videomode * vm</code></dt> <dd>videomode structure to use</dd> <dt><code class="docutils literal">u32 * bus_flags</code></dt> <dd>information about pixelclk and DE polarity will be stored here</dd> </dl> Description Sets DRM_BUS_FLAG_DE_(LOW|HIGH) and DRM_BUS_FLAG_PIXDATA_(POS|NEG)EDGE in bus_flags according to DISPLAY_FLAGS found in vm <dl class="function"> <dt id="c.of_get_drm_display_mode"> int <code class="descname">of_get_drm_display_mode</code>(struct device_node * np, struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * dmode, u32 * bus_flags, int index)<a class="headerlink" href="#c.of_get_drm_display_mode" title="Permalink to this definition">¶</a></dt> <dd>get a drm_display_mode from devicetree </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct device_node * np</code></dt> <dd>device_node with the timing specification</dd> <dt><code class="docutils literal">struct drm_display_mode * dmode</code></dt> <dd>will be set to the return value</dd> <dt><code class="docutils literal">u32 * bus_flags</code></dt> <dd>information about pixelclk and DE polarity</dd> <dt><code class="docutils literal">int index</code></dt> <dd>index into the list of display timings in devicetree</dd> </dl> Description This function is expensive and should only be used, if only one mode is to be read from DT. To get multiple modes start with of_get_display_timings and work with that instead. Return 0 on success, a negative errno code when no of videomode node was found. <dl class="function"> <dt id="c.drm_mode_set_name"> void <code class="descname">drm_mode_set_name</code>(struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_set_name" title="Permalink to this definition">¶</a></dt> <dd>set the name on a mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_display_mode * mode</code></dt> <dd>name will be set in this mode</dd> </dl> Description Set the name of mode to a standard format which is <hdisplay>x<vdisplay> with an optional ‘i’ suffix for interlaced modes. <dl class="function"> <dt id="c.drm_mode_hsync"> int <code class="descname">drm_mode_hsync</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_hsync" title="Permalink to this definition">¶</a></dt> <dd>get the hsync of a mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode</dd> </dl> Return modes‘s hsync rate in kHz, rounded to the nearest integer. Calculates the value first if it is not yet set. <dl class="function"> <dt id="c.drm_mode_vrefresh"> int <code class="descname">drm_mode_vrefresh</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_vrefresh" title="Permalink to this definition">¶</a></dt> <dd>get the vrefresh of a mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode</dd> </dl> Return modes‘s vrefresh rate in Hz, rounded to the nearest integer. Calculates the value first if it is not yet set. <dl class="function"> <dt id="c.drm_mode_get_hv_timing"> void <code class="descname">drm_mode_get_hv_timing</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode, int * hdisplay, int * vdisplay)<a class="headerlink" href="#c.drm_mode_get_hv_timing" title="Permalink to this definition">¶</a></dt> <dd>Fetches hdisplay/vdisplay for given mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to query</dd> <dt><code class="docutils literal">int * hdisplay</code></dt> <dd>hdisplay value to fill in</dd> <dt><code class="docutils literal">int * vdisplay</code></dt> <dd>vdisplay value to fill in</dd> </dl> Description The vdisplay value will be doubled if the specified mode is a stereo mode of the appropriate layout. <dl class="function"> <dt id="c.drm_mode_set_crtcinfo"> void <code class="descname">drm_mode_set_crtcinfo</code>(struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * p, int adjust_flags)<a class="headerlink" href="#c.drm_mode_set_crtcinfo" title="Permalink to this definition">¶</a></dt> <dd>set CRTC modesetting timing parameters </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_display_mode * p</code></dt> <dd>mode</dd> <dt><code class="docutils literal">int adjust_flags</code></dt> <dd>a combination of adjustment flags</dd> </dl> Description Setup the CRTC modesetting timing parameters for p, adjusting if necessary. <ul class="simple"> <li>The CRTC_INTERLACE_HALVE_V flag can be used to halve vertical timings of interlaced modes.</li> <li>The CRTC_STEREO_DOUBLE flag can be used to compute the timings for buffers containing two eyes (only adjust the timings when needed, eg. for “frame packing” or “side by side full”).</li> <li>The CRTC_NO_DBLSCAN and CRTC_NO_VSCAN flags request that adjustment not be performed for doublescan and vscan > 1 modes respectively.</li> </ul> <dl class="function"> <dt id="c.drm_mode_copy"> void <code class="descname">drm_mode_copy</code>(struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * dst, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * src)<a class="headerlink" href="#c.drm_mode_copy" title="Permalink to this definition">¶</a></dt> <dd>copy the mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_display_mode * dst</code></dt> <dd>mode to overwrite</dd> <dt><code class="docutils literal">const struct drm_display_mode * src</code></dt> <dd>mode to copy</dd> </dl> Description Copy an existing mode into another mode, preserving the object id and list head of the destination mode. <dl class="function"> <dt id="c.drm_mode_duplicate"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_mode_duplicate</code>(struct drm_device * dev, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_duplicate" title="Permalink to this definition">¶</a></dt> <dd>allocate and duplicate an existing mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm_device to allocate the duplicated mode for</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to duplicate</dd> </dl> Description Just allocate a new mode, copy the existing mode into it, and return a pointer to it. Used to create new instances of established modes. Return Pointer to duplicated mode on success, NULL on error. <dl class="function"> <dt id="c.drm_mode_equal"> bool <code class="descname">drm_mode_equal</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode1, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode2)<a class="headerlink" href="#c.drm_mode_equal" title="Permalink to this definition">¶</a></dt> <dd>test modes for equality </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode1</code></dt> <dd>first mode</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode2</code></dt> <dd>second mode</dd> </dl> Description Check to see if mode1 and mode2 are equivalent. Return True if the modes are equal, false otherwise. <dl class="function"> <dt id="c.drm_mode_equal_no_clocks"> bool <code class="descname">drm_mode_equal_no_clocks</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode1, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode2)<a class="headerlink" href="#c.drm_mode_equal_no_clocks" title="Permalink to this definition">¶</a></dt> <dd>test modes for equality </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode1</code></dt> <dd>first mode</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode2</code></dt> <dd>second mode</dd> </dl> Description Check to see if mode1 and mode2 are equivalent, but don’t check the pixel clocks. Return True if the modes are equal, false otherwise. <dl class="function"> <dt id="c.drm_mode_equal_no_clocks_no_stereo"> bool <code class="descname">drm_mode_equal_no_clocks_no_stereo</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode1, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode2)<a class="headerlink" href="#c.drm_mode_equal_no_clocks_no_stereo" title="Permalink to this definition">¶</a></dt> <dd>test modes for equality </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode1</code></dt> <dd>first mode</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode2</code></dt> <dd>second mode</dd> </dl> Description Check to see if mode1 and mode2 are equivalent, but don’t check the pixel clocks nor the stereo layout. Return True if the modes are equal, false otherwise. <dl class="function"> <dt id="c.drm_mode_validate_basic"> enum <a class="reference internal" href="#c.drm_mode_status" title="drm_mode_status">drm_mode_status</a> <code class="descname">drm_mode_validate_basic</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_validate_basic" title="Permalink to this definition">¶</a></dt> <dd>make sure the mode is somewhat sane </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to check</dd> </dl> Description Check that the mode timings are at least somewhat reasonable. Any hardware specific limits are left up for each driver to check. Return The mode status <dl class="function"> <dt id="c.drm_mode_validate_size"> enum <a class="reference internal" href="#c.drm_mode_status" title="drm_mode_status">drm_mode_status</a> <code class="descname">drm_mode_validate_size</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode, int maxX, int maxY)<a class="headerlink" href="#c.drm_mode_validate_size" title="Permalink to this definition">¶</a></dt> <dd>make sure modes adhere to size constraints </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to check</dd> <dt><code class="docutils literal">int maxX</code></dt> <dd>maximum width</dd> <dt><code class="docutils literal">int maxY</code></dt> <dd>maximum height</dd> </dl> Description This function is a helper which can be used to validate modes against size limitations of the DRM device/connector. If a mode is too big its status member is updated with the appropriate validation failure code. The list itself is not changed. Return The mode status <dl class="function"> <dt id="c.drm_mode_validate_ycbcr420"> enum <a class="reference internal" href="#c.drm_mode_status" title="drm_mode_status">drm_mode_status</a> <code class="descname">drm_mode_validate_ycbcr420</code>(const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_mode_validate_ycbcr420" title="Permalink to this definition">¶</a></dt> <dd>add ‘ycbcr420-only’ modes only when allowed </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>mode to check</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>drm connector under action</dd> </dl> Description This function is a helper which can be used to filter out any YCBCR420 only mode, when the source doesn’t support it. Return The mode status <dl class="function"> <dt id="c.drm_mode_prune_invalid"> void <code class="descname">drm_mode_prune_invalid</code>(struct drm_device * dev, struct list_head * mode_list, bool verbose)<a class="headerlink" href="#c.drm_mode_prune_invalid" title="Permalink to this definition">¶</a></dt> <dd>remove invalid modes from mode list </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct list_head * mode_list</code></dt> <dd>list of modes to check</dd> <dt><code class="docutils literal">bool verbose</code></dt> <dd>be verbose about it</dd> </dl> Description This helper function can be used to prune a display mode list after validation has been completed. All modes who’s status is not MODE_OK will be removed from the list, and if verbose the status code and mode name is also printed to dmesg. <dl class="function"> <dt id="c.drm_mode_sort"> void <code class="descname">drm_mode_sort</code>(struct list_head * mode_list)<a class="headerlink" href="#c.drm_mode_sort" title="Permalink to this definition">¶</a></dt> <dd>sort mode list </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct list_head * mode_list</code></dt> <dd>list of drm_display_mode structures to sort</dd> </dl> Description Sort mode_list by favorability, moving good modes to the head of the list. <dl class="function"> <dt id="c.drm_mode_connector_list_update"> void <code class="descname">drm_mode_connector_list_update</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_mode_connector_list_update" title="Permalink to this definition">¶</a></dt> <dd>update the mode list for the connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>the connector to update</dd> </dl> Description This moves the modes from the connector probed_modes list to the actual mode list. It compares the probed mode against the current list and only adds different/new modes. This is just a helper functions doesn’t validate any modes itself and also doesn’t prune any invalid modes. Callers need to do that themselves. <dl class="function"> <dt id="c.drm_mode_parse_command_line_for_connector"> bool <code class="descname">drm_mode_parse_command_line_for_connector</code>(const char * mode_option, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, struct drm_cmdline_mode * mode)<a class="headerlink" href="#c.drm_mode_parse_command_line_for_connector" title="Permalink to this definition">¶</a></dt> <dd>parse command line modeline for connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const char * mode_option</code></dt> <dd>optional per connector mode option</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to parse modeline for</dd> <dt><code class="docutils literal">struct drm_cmdline_mode * mode</code></dt> <dd>preallocated drm_cmdline_mode structure to fill out</dd> </dl> Description This parses mode_option command line modeline for modes and options to configure the connector. If mode_option is NULL the default command line modeline in fb_mode_option will be parsed instead. This uses the same parameters as the fb modedb.c, except for an extra force-enable, force-enable-digital and force-disable bit at the end: <xres>x<yres>[M][R][-<bpp>][<a href="#id1">**</a><a href="#id3">**</a><refresh>][i][m][eDd] The intermediate drm_cmdline_mode structure is required to store additional options from the command line modline like the force-enable/disable flag. Return True if a valid modeline has been parsed, false otherwise. <dl class="function"> <dt id="c.drm_mode_create_from_cmdline_mode"> struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * <code class="descname">drm_mode_create_from_cmdline_mode</code>(struct drm_device * dev, struct drm_cmdline_mode * cmd)<a class="headerlink" href="#c.drm_mode_create_from_cmdline_mode" title="Permalink to this definition">¶</a></dt> <dd>convert a command line modeline into a DRM display mode </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device to create the new mode for</dd> <dt><code class="docutils literal">struct drm_cmdline_mode * cmd</code></dt> <dd>input command line modeline</dd> </dl> Return Pointer to converted mode on success, NULL on error. <dl class="function"> <dt id="c.drm_mode_is_420_only"> bool <code class="descname">drm_mode_is_420_only</code>(const struct <a class="reference internal" href="#c.drm_display_info" title="drm_display_info">drm_display_info</a> * display, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_is_420_only" title="Permalink to this definition">¶</a></dt> <dd>if a given videomode can be only supported in YCBCR420 output format </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_info * display</code></dt> <dd>display under action</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>video mode to be tested.</dd> </dl> Return true if the mode can be supported in YCBCR420 format false if not. <dl class="function"> <dt id="c.drm_mode_is_420_also"> bool <code class="descname">drm_mode_is_420_also</code>(const struct <a class="reference internal" href="#c.drm_display_info" title="drm_display_info">drm_display_info</a> * display, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_is_420_also" title="Permalink to this definition">¶</a></dt> <dd>if a given videomode can be supported in YCBCR420 output format also (along with RGB/YCBCR444/422) </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_info * display</code></dt> <dd>display under action.</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>video mode to be tested.</dd> </dl> Return true if the mode can be support YCBCR420 format false if not. <dl class="function"> <dt id="c.drm_mode_is_420"> bool <code class="descname">drm_mode_is_420</code>(const struct <a class="reference internal" href="#c.drm_display_info" title="drm_display_info">drm_display_info</a> * display, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_mode_is_420" title="Permalink to this definition">¶</a></dt> <dd>if a given videomode can be supported in YCBCR420 output format </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">const struct drm_display_info * display</code></dt> <dd>display under action.</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>video mode to be tested.</dd> </dl> Return true if the mode can be supported in YCBCR420 format false if not. </div> <div class="section" id="connector-abstraction"> <h2>Connector Abstraction<a class="headerlink" href="#connector-abstraction" title="Permalink to this headline">¶</a></h2> In DRM connectors are the general abstraction for display sinks, and include als fixed panels or anything else that can display pixels in some form. As opposed to all other KMS objects representing hardware (like CRTC, encoder or plane abstractions) connectors can be hotplugged and unplugged at runtime. Hence they are reference-counted using <a class="reference internal" href="#c.drm_connector_get" title="drm_connector_get"><code class="xref c c-func docutils literal">drm_connector_get()</code></a> and <a class="reference internal" href="#c.drm_connector_put" title="drm_connector_put"><code class="xref c c-func docutils literal">drm_connector_put()</code></a>. KMS driver must create, initialize, register and attach at a <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> for each such sink. The instance is created as other KMS objects and initialized by setting the following fields. The connector is initialized with a call to <a class="reference internal" href="#c.drm_connector_init" title="drm_connector_init"><code class="xref c c-func docutils literal">drm_connector_init()</code></a> with a pointer to the <a class="reference internal" href="#c.drm_connector_funcs" title="drm_connector_funcs"><code class="xref c c-type docutils literal">struct drm_connector_funcs</code></a> and a connector type, and then exposed to userspace with a call to <a class="reference internal" href="#c.drm_connector_register" title="drm_connector_register"><code class="xref c c-func docutils literal">drm_connector_register()</code></a>. Connectors must be attached to an encoder to be used. For devices that map connectors to encoders 1:1, the connector should be attached at initialization time with a call to <a class="reference internal" href="#c.drm_mode_connector_attach_encoder" title="drm_mode_connector_attach_encoder"><code class="xref c c-func docutils literal">drm_mode_connector_attach_encoder()</code></a>. The driver must also set the <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.encoder</code></a> field to point to the attached encoder. For connectors which are not fixed (like built-in panels) the driver needs to support hotplug notifications. The simplest way to do that is by using the probe helpers, see <a class="reference internal" href="drm-kms-helpers.html#c.drm_kms_helper_poll_init" title="drm_kms_helper_poll_init"><code class="xref c c-func docutils literal">drm_kms_helper_poll_init()</code></a> for connectors which don’t have hardware support for hotplug interrupts. Connectors with hardware hotplug support can instead use e.g. <a class="reference internal" href="drm-kms-helpers.html#c.drm_helper_hpd_irq_event" title="drm_helper_hpd_irq_event"><code class="xref c c-func docutils literal">drm_helper_hpd_irq_event()</code></a>. <div class="section" id="connector-functions-reference"> <h3>Connector Functions Reference<a class="headerlink" href="#connector-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_connector_status"> enum <code class="descname">drm_connector_status</code><a class="headerlink" href="#c.drm_connector_status" title="Permalink to this definition">¶</a></dt> <dd>status for a <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a> </dd></dl> Constants <dl class="docutils"> <dt><code class="docutils literal">connector_status_connected</code></dt> <dd>The connector is definitely connected to a sink device, and can be enabled.</dd> <dt><code class="docutils literal">connector_status_disconnected</code></dt> <dd>The connector isn’t connected to a sink device which can be autodetect. For digital outputs like DP or HDMI (which can be realiable probed) this means there’s really nothing there. It is driver-dependent whether a connector with this status can be lit up or not.</dd> <dt><code class="docutils literal">connector_status_unknown</code></dt> <dd>The connector’s status could not be reliably detected. This happens when probing would either cause flicker (like load-detection when the connector is in use), or when a hardware resource isn’t available (like when load-detection needs a free CRTC). It should be possible to light up the connector with one of the listed fallback modes. For default configuration userspace should only try to light up connectors with unknown status when there’s not connector with connector_status_connected.</dd> </dl> Description This enum is used to track the connector status. There are no separate #defines for the uapi! <dl class="type"> <dt id="c.drm_scrambling"> struct <code class="descname">drm_scrambling</code><a class="headerlink" href="#c.drm_scrambling" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_scrambling { bool supported; bool low_rates; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">supported</code></dt> <dd>scrambling supported for rates > 340 Mhz.</dd> <dt><code class="docutils literal">low_rates</code></dt> <dd>scrambling supported for rates <= 340 Mhz.</dd> </dl> <dl class="type"> <dt id="c.drm_hdmi_info"> struct <code class="descname">drm_hdmi_info</code><a class="headerlink" href="#c.drm_hdmi_info" title="Permalink to this definition">¶</a></dt> <dd>runtime information about the connected HDMI sink </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_hdmi_info { struct drm_scdc scdc; unsigned long y420_vdb_modes[BITS_TO_LONGS(128)]; unsigned long y420_cmdb_modes[BITS_TO_LONGS(128)]; u64 y420_cmdb_map; u8 y420_dc_modes; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">scdc</code></dt> <dd>sink’s scdc support and capabilities</dd> <dt><code class="docutils literal">y420_vdb_modes</code></dt> <dd>bitmap of modes which can support ycbcr420 output only (not normal RGB/YCBCR444/422 outputs). There are total 107 VICs defined by CEA-861-F spec, so the size is 128 bits to map upto 128 VICs;</dd> <dt><code class="docutils literal">y420_cmdb_modes</code></dt> <dd>bitmap of modes which can support ycbcr420 output also, along with normal HDMI outputs. There are total 107 VICs defined by CEA-861-F spec, so the size is 128 bits to map upto 128 VICs;</dd> <dt><code class="docutils literal">y420_cmdb_map</code></dt> <dd>bitmap of SVD index, to extraxt vcb modes</dd> <dt><code class="docutils literal">y420_dc_modes</code></dt> <dd>bitmap of deep color support index</dd> </dl> Description Describes if a given display supports advanced HDMI 2.0 features. This information is available in CEA-861-F extension blocks (like HF-VSDB). <dl class="type"> <dt id="c.drm_link_status"> enum <code class="descname">drm_link_status</code><a class="headerlink" href="#c.drm_link_status" title="Permalink to this definition">¶</a></dt> <dd>connector’s link_status property value </dd></dl> Constants <dl class="docutils"> <dt><code class="docutils literal">DRM_LINK_STATUS_GOOD</code></dt> <dd>DP Link is Good as a result of successful link training</dd> <dt><code class="docutils literal">DRM_LINK_STATUS_BAD</code></dt> <dd>DP Link is BAD as a result of link training failure</dd> </dl> Description This enum is used as the connector’s link status property value. It is set to the values defined in uapi. <dl class="type"> <dt id="c.drm_panel_orientation"> enum <code class="descname">drm_panel_orientation</code><a class="headerlink" href="#c.drm_panel_orientation" title="Permalink to this definition">¶</a></dt> <dd>panel_orientation info for <a class="reference internal" href="#c.drm_display_info" title="drm_display_info"><code class="xref c c-type docutils literal">drm_display_info</code></a> </dd></dl> Constants <dl class="docutils"> <dt><code class="docutils literal">DRM_MODE_PANEL_ORIENTATION_UNKNOWN</code></dt> <dd>The drm driver has not provided any panel orientation information (normal for non panels) in this case the “panel orientation” connector prop will not be attached.</dd> <dt><code class="docutils literal">DRM_MODE_PANEL_ORIENTATION_NORMAL</code></dt> <dd>The top side of the panel matches the top side of the device’s casing.</dd> <dt><code class="docutils literal">DRM_MODE_PANEL_ORIENTATION_BOTTOM_UP</code></dt> <dd>The top side of the panel matches the bottom side of the device’s casing, iow the panel is mounted upside-down.</dd> <dt><code class="docutils literal">DRM_MODE_PANEL_ORIENTATION_LEFT_UP</code></dt> <dd>The left side of the panel matches the top side of the device’s casing.</dd> <dt><code class="docutils literal">DRM_MODE_PANEL_ORIENTATION_RIGHT_UP</code></dt> <dd>The right side of the panel matches the top side of the device’s casing.</dd> </dl> Description This enum is used to track the (LCD) panel orientation. There are no separate #defines for the uapi! <dl class="type"> <dt id="c.drm_display_info"> struct <code class="descname">drm_display_info</code><a class="headerlink" href="#c.drm_display_info" title="Permalink to this definition">¶</a></dt> <dd>runtime data about the connected sink </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_display_info { char name[DRM_DISPLAY_INFO_LEN]; unsigned int width_mm; unsigned int height_mm; unsigned int pixel_clock; unsigned int bpc; enum subpixel_order subpixel_order; #define DRM_COLOR_FORMAT_RGB444 (1<<0); #define DRM_COLOR_FORMAT_YCRCB444 (1<<1); #define DRM_COLOR_FORMAT_YCRCB422 (1<<2); #define DRM_COLOR_FORMAT_YCRCB420 (1<<3); int panel_orientation; u32 color_formats; const u32 *bus_formats; unsigned int num_bus_formats; #define DRM_BUS_FLAG_DE_LOW (1<<0); #define DRM_BUS_FLAG_DE_HIGH (1<<1); #define DRM_BUS_FLAG_PIXDATA_POSEDGE (1<<2); #define DRM_BUS_FLAG_PIXDATA_NEGEDGE (1<<3); #define DRM_BUS_FLAG_DATA_MSB_TO_LSB (1<<4); #define DRM_BUS_FLAG_DATA_LSB_TO_MSB (1<<5); u32 bus_flags; int max_tmds_clock; bool dvi_dual; bool has_hdmi_infoframe; u8 edid_hdmi_dc_modes; u8 cea_rev; struct drm_hdmi_info hdmi; bool non_desktop; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">name</code></dt> <dd>Name of the display.</dd> <dt><code class="docutils literal">width_mm</code></dt> <dd>Physical width in mm.</dd> <dt><code class="docutils literal">height_mm</code></dt> <dd>Physical height in mm.</dd> <dt><code class="docutils literal">pixel_clock</code></dt> <dd>Maximum pixel clock supported by the sink, in units of 100Hz. This mismatches the clock in <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode"><code class="xref c c-type docutils literal">drm_display_mode</code></a> (which is in kHZ), because that’s what the EDID uses as base unit.</dd> <dt><code class="docutils literal">bpc</code></dt> <dd>Maximum bits per color channel. Used by HDMI and DP outputs.</dd> <dt><code class="docutils literal">subpixel_order</code></dt> <dd>Subpixel order of LCD panels.</dd> <dt><code class="docutils literal">panel_orientation</code></dt> <dd>Read only connector property for built-in panels, indicating the orientation of the panel vs the device’s casing. <a class="reference internal" href="#c.drm_connector_init" title="drm_connector_init"><code class="xref c c-func docutils literal">drm_connector_init()</code></a> sets this to DRM_MODE_PANEL_ORIENTATION_UNKNOWN. When not UNKNOWN this gets used by the drm_fb_helpers to rotate the fb to compensate and gets exported as prop to userspace.</dd> <dt><code class="docutils literal">color_formats</code></dt> <dd>HDMI Color formats, selects between RGB and YCrCb modes. Used DRM_COLOR_FORMAT_ defines, which are _not_ the same ones as used to describe the pixel format in framebuffers, and also don’t match the formats in bus_formats which are shared with v4l.</dd> <dt><code class="docutils literal">bus_formats</code></dt> <dd>Pixel data format on the wire, somewhat redundant with color_formats. Array of size num_bus_formats encoded using MEDIA_BUS_FMT_ defines shared with v4l and media drivers.</dd> <dt><code class="docutils literal">num_bus_formats</code></dt> <dd>Size of bus_formats array.</dd> <dt><code class="docutils literal">bus_flags</code></dt> <dd>Additional information (like pixel signal polarity) for the pixel data on the bus, using DRM_BUS_FLAGS_ defines.</dd> <dt><code class="docutils literal">max_tmds_clock</code></dt> <dd>Maximum TMDS clock rate supported by the sink in kHz. 0 means undefined.</dd> <dt><code class="docutils literal">dvi_dual</code></dt> <dd>Dual-link DVI sink?</dd> <dt><code class="docutils literal">has_hdmi_infoframe</code></dt> <dd>Does the sink support the HDMI infoframe?</dd> <dt><code class="docutils literal">edid_hdmi_dc_modes</code></dt> <dd>Mask of supported hdmi deep color modes. Even more stuff redundant with bus_formats.</dd> <dt><code class="docutils literal">cea_rev</code></dt> <dd>CEA revision of the HDMI sink.</dd> <dt><code class="docutils literal">hdmi</code></dt> <dd>advance features of a HDMI sink.</dd> <dt><code class="docutils literal">non_desktop</code></dt> <dd>Non desktop display (HMD).</dd> </dl> Description Describes a given display (e.g. CRT or flat panel) and its limitations. For fixed display sinks like built-in panels there’s not much difference between this and <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a>. But for sinks with a real cable this structure is meant to describe all the things at the other end of the cable. For sinks which provide an EDID this can be filled out by calling <a class="reference internal" href="drm-kms-helpers.html#c.drm_add_edid_modes" title="drm_add_edid_modes"><code class="xref c c-func docutils literal">drm_add_edid_modes()</code></a>. <dl class="type"> <dt id="c.drm_tv_connector_state"> struct <code class="descname">drm_tv_connector_state</code><a class="headerlink" href="#c.drm_tv_connector_state" title="Permalink to this definition">¶</a></dt> <dd>TV connector related states </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_tv_connector_state { enum drm_mode_subconnector subconnector; struct { unsigned int left; unsigned int right; unsigned int top; unsigned int bottom; } margins; unsigned int mode; unsigned int brightness; unsigned int contrast; unsigned int flicker_reduction; unsigned int overscan; unsigned int saturation; unsigned int hue; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">subconnector</code></dt> <dd>selected subconnector</dd> <dt><code class="docutils literal">margins</code></dt> <dd>left/right/top/bottom margins</dd> <dt><code class="docutils literal">mode</code></dt> <dd>TV mode</dd> <dt><code class="docutils literal">brightness</code></dt> <dd>brightness in percent</dd> <dt><code class="docutils literal">contrast</code></dt> <dd>contrast in percent</dd> <dt><code class="docutils literal">flicker_reduction</code></dt> <dd>flicker reduction in percent</dd> <dt><code class="docutils literal">overscan</code></dt> <dd>overscan in percent</dd> <dt><code class="docutils literal">saturation</code></dt> <dd>saturation in percent</dd> <dt><code class="docutils literal">hue</code></dt> <dd>hue in percent</dd> </dl> <dl class="type"> <dt id="c.drm_connector_state"> struct <code class="descname">drm_connector_state</code><a class="headerlink" href="#c.drm_connector_state" title="Permalink to this definition">¶</a></dt> <dd>mutable connector state </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_connector_state { struct drm_connector *connector; struct drm_crtc *crtc; struct drm_encoder *best_encoder; enum drm_link_status link_status; struct drm_atomic_state *state; struct drm_crtc_commit *commit; struct drm_tv_connector_state tv; enum hdmi_picture_aspect picture_aspect_ratio; unsigned int scaling_mode; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">connector</code></dt> <dd>backpointer to the connector</dd> <dt><code class="docutils literal">crtc</code></dt> <dd>CRTC to connect connector to, NULL if disabled. Do not change this directly, use <a class="reference internal" href="#c.drm_atomic_set_crtc_for_connector" title="drm_atomic_set_crtc_for_connector"><code class="xref c c-func docutils literal">drm_atomic_set_crtc_for_connector()</code></a> instead. </dd> <dt><code class="docutils literal">best_encoder</code></dt> <dd>can be used by helpers and drivers to select the encoder</dd> <dt><code class="docutils literal">link_status</code></dt> <dd>Connector link_status to keep track of whether link is GOOD or BAD to notify userspace if retraining is necessary.</dd> <dt><code class="docutils literal">state</code></dt> <dd>backpointer to global drm_atomic_state</dd> <dt><code class="docutils literal">commit</code></dt> <dd>Tracks the pending commit to prevent use-after-free conditions. Is only set when crtc is NULL. </dd> <dt><code class="docutils literal">tv</code></dt> <dd>TV connector state</dd> <dt><code class="docutils literal">picture_aspect_ratio</code></dt> <dd>Connector property to control the HDMI infoframe aspect ratio setting. The <code class="docutils literal">DRM_MODE_PICTURE_ASPECT_</code>* values much match the values for <code class="xref c c-type docutils literal">enum hdmi_picture_aspect</code> </dd> <dt><code class="docutils literal">scaling_mode</code></dt> <dd>Connector property to control the upscaling, mostly used for built-in panels.</dd> </dl> <dl class="type"> <dt id="c.drm_connector_funcs"> struct <code class="descname">drm_connector_funcs</code><a class="headerlink" href="#c.drm_connector_funcs" title="Permalink to this definition">¶</a></dt> <dd>control connectors on a given device </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_connector_funcs { int (*dpms)(struct drm_connector *connector, int mode); void (*reset)(struct drm_connector *connector); enum drm_connector_status (*detect)(struct drm_connector *connector, bool force); void (*force)(struct drm_connector *connector); int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height); int (*set_property)(struct drm_connector *connector, struct drm_property *property, uint64_t val); int (*late_register)(struct drm_connector *connector); void (*early_unregister)(struct drm_connector *connector); void (*destroy)(struct drm_connector *connector); struct drm_connector_state *(*atomic_duplicate_state)(struct drm_connector *connector); void (*atomic_destroy_state)(struct drm_connector *connector, struct drm_connector_state *state); int (*atomic_set_property)(struct drm_connector *connector,struct drm_connector_state *state,struct drm_property *property, uint64_t val); int (*atomic_get_property)(struct drm_connector *connector,const struct drm_connector_state *state,struct drm_property *property, uint64_t *val); void (*atomic_print_state)(struct drm_printer *p, const struct drm_connector_state *state); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dpms</code></dt> <dd>Legacy entry point to set the per-connector DPMS state. Legacy DPMS is exposed as a standard property on the connector, but diverted to this callback in the drm core. Note that atomic drivers don’t implement the 4 level DPMS support on the connector any more, but instead only have an on/off “ACTIVE” property on the CRTC object. This hook is not used by atomic drivers, remapping of the legacy DPMS property is entirely handled in the DRM core. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">reset</code></dt> <dd>Reset connector hardware and software state to off. This function isn’t called by the core directly, only through <a class="reference internal" href="#c.drm_mode_config_reset" title="drm_mode_config_reset"><code class="xref c c-func docutils literal">drm_mode_config_reset()</code></a>. It’s not a helper hook only for historical reasons. Atomic drivers can use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_connector_reset" title="drm_atomic_helper_connector_reset"><code class="xref c c-func docutils literal">drm_atomic_helper_connector_reset()</code></a> to reset atomic state using this hook. </dd> <dt><code class="docutils literal">detect</code></dt> <dd>Check to see if anything is attached to the connector. The parameter force is set to false whilst polling, true when checking the connector due to a user request. force can be used by the driver to avoid expensive, destructive operations during automated probing. This callback is optional, if not implemented the connector will be considered as always being attached. FIXME: Note that this hook is only called by the probe helper. It’s not in the helper library vtable purely for historical reasons. The only DRM core entry point to probe connector state is fill_modes. Note that the helper library will already hold <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.connection_mutex</code></a>. Drivers which need to grab additional locks to avoid races with concurrent modeset changes need to use <a class="reference internal" href="drm-kms-helpers.html#c.drm_connector_helper_funcs" title="drm_connector_helper_funcs"><code class="xref c c-type docutils literal">drm_connector_helper_funcs.detect_ctx</code></a> instead. RETURNS: drm_connector_status indicating the connector’s status. </dd> <dt><code class="docutils literal">force</code></dt> <dd>This function is called to update internal encoder state when the connector is forced to a certain state by userspace, either through the sysfs interfaces or on the kernel cmdline. In that case the detect callback isn’t called. FIXME: Note that this hook is only called by the probe helper. It’s not in the helper library vtable purely for historical reasons. The only DRM core entry point to probe connector state is fill_modes. </dd> <dt><code class="docutils literal">fill_modes</code></dt> <dd>Entry point for output detection and basic mode validation. The driver should reprobe the output if needed (e.g. when hotplug handling is unreliable), add all detected modes to <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.modes</code></a> and filter out any the device can’t support in any configuration. It also needs to filter out any modes wider or higher than the parameters max_width and max_height indicate. The drivers must also prune any modes no longer valid from <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.modes</code></a>. Furthermore it must update <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.status</code></a> and <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.edid</code></a>. If no EDID has been received for this output connector->edid must be NULL. Drivers using the probe helpers should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_helper_probe_single_connector_modes" title="drm_helper_probe_single_connector_modes"><code class="xref c c-func docutils literal">drm_helper_probe_single_connector_modes()</code></a> or <code class="xref c c-func docutils literal">drm_helper_probe_single_connector_modes_nomerge()</code> to implement this function. RETURNS: The number of modes detected and filled into <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.modes</code></a>. </dd> <dt><code class="docutils literal">set_property</code></dt> <dd>This is the legacy entry point to update a property attached to the connector. This callback is optional if the driver does not support any legacy driver-private properties. For atomic drivers it is not used because property handling is done entirely in the DRM core. RETURNS: 0 on success or a negative error code on failure. </dd> <dt><code class="docutils literal">late_register</code></dt> <dd>This optional hook can be used to register additional userspace interfaces attached to the connector, light backlight control, i2c, DP aux or similar interfaces. It is called late in the driver load sequence from <a class="reference internal" href="#c.drm_connector_register" title="drm_connector_register"><code class="xref c c-func docutils literal">drm_connector_register()</code></a> when registering all the core drm connector interfaces. Everything added from this callback should be unregistered in the early_unregister callback. This is called while holding <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.mutex</code></a>. Returns: 0 on success, or a negative error code on failure. </dd> <dt><code class="docutils literal">early_unregister</code></dt> <dd>This optional hook should be used to unregister the additional userspace interfaces attached to the connector from <code class="xref c c-func docutils literal">late_register()</code>. It is called from <a class="reference internal" href="#c.drm_connector_unregister" title="drm_connector_unregister"><code class="xref c c-func docutils literal">drm_connector_unregister()</code></a>, early in the driver unload sequence to disable userspace access before data structures are torndown. This is called while holding <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.mutex</code></a>. </dd> <dt><code class="docutils literal">destroy</code></dt> <dd>Clean up connector resources. This is called at driver unload time through <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. It can also be called at runtime when a connector is being hot-unplugged for drivers that support connector hotplugging (e.g. DisplayPort MST).</dd> <dt><code class="docutils literal">atomic_duplicate_state</code></dt> <dd>Duplicate the current atomic state for this connector and return it. The core and helpers guarantee that any atomic state duplicated with this hook and still owned by the caller (i.e. not transferred to the driver by calling <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_commit</code></a>) will be cleaned up by calling the atomic_destroy_state hook in this structure. Atomic drivers which don’t subclass <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a> should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_connector_duplicate_state" title="drm_atomic_helper_connector_duplicate_state"><code class="xref c c-func docutils literal">drm_atomic_helper_connector_duplicate_state()</code></a>. Drivers that subclass the state structure to extend it with driver-private state should use <a class="reference internal" href="drm-kms-helpers.html#c.__drm_atomic_helper_connector_duplicate_state" title="__drm_atomic_helper_connector_duplicate_state"><code class="xref c c-func docutils literal">__drm_atomic_helper_connector_duplicate_state()</code></a> to make sure shared state is duplicated in a consistent fashion across drivers. It is an error to call this hook before <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector.state</code></a> has been initialized correctly. NOTE: If the duplicate state references refcounted resources this hook must acquire a reference for each of them. The driver must release these references again in atomic_destroy_state. RETURNS: Duplicated atomic state or NULL when the allocation failed. </dd> <dt><code class="docutils literal">atomic_destroy_state</code></dt> <dd>Destroy a state duplicated with atomic_duplicate_state and release or unreference all resources it references</dd> <dt><code class="docutils literal">atomic_set_property</code></dt> <dd>Decode a driver-private property value and store the decoded value into the passed-in state structure. Since the atomic core decodes all standardized properties (even for extensions beyond the core set of properties which might not be implemented by all drivers) this requires drivers to subclass the state structure. Such driver-private properties should really only be implemented for truly hardware/vendor specific state. Instead it is preferred to standardize atomic extension and decode the properties used to expose such an extension in the core. Do not call this function directly, use <code class="xref c c-func docutils literal">drm_atomic_connector_set_property()</code> instead. This callback is optional if the driver does not support any driver-private atomic properties. NOTE: This function is called in the state assembly phase of atomic modesets, which can be aborted for any reason (including on userspace’s request to just check whether a configuration would be possible). Drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in state parameter. Also since userspace controls in which order properties are set this function must not do any input validation (since the state update is incomplete and hence likely inconsistent). Instead any such input validation must be done in the various atomic_check callbacks. RETURNS: 0 if the property has been found, -EINVAL if the property isn’t implemented by the driver (which shouldn’t ever happen, the core only asks for properties attached to this connector). No other validation is allowed by the driver. The core already checks that the property value is within the range (integer, valid enum value, ...) the driver set when registering the property. </dd> <dt><code class="docutils literal">atomic_get_property</code></dt> <dd>Reads out the decoded driver-private property. This is used to implement the GETCONNECTOR IOCTL. Do not call this function directly, use <code class="xref c c-func docutils literal">drm_atomic_connector_get_property()</code> instead. This callback is optional if the driver does not support any driver-private atomic properties. RETURNS: 0 on success, -EINVAL if the property isn’t implemented by the driver (which shouldn’t ever happen, the core only asks for properties attached to this connector). </dd> <dt><code class="docutils literal">atomic_print_state</code></dt> <dd>If driver subclasses <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">struct drm_connector_state</code></a>, it should implement this optional hook for printing additional driver specific state. Do not call this directly, use <code class="xref c c-func docutils literal">drm_atomic_connector_print_state()</code> instead. </dd> </dl> Description Each CRTC may have one or more connectors attached to it. The functions below allow the core DRM code to control connectors, enumerate available modes, etc. <dl class="type"> <dt id="c.drm_connector"> struct <code class="descname">drm_connector</code><a class="headerlink" href="#c.drm_connector" title="Permalink to this definition">¶</a></dt> <dd>central DRM connector control structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_connector { struct drm_device *dev; struct device *kdev; struct device_attribute *attr; struct list_head head; struct drm_mode_object base; char *name; struct mutex mutex; unsigned index; int connector_type; int connector_type_id; bool interlace_allowed; bool doublescan_allowed; bool stereo_allowed; bool ycbcr_420_allowed; bool registered; struct list_head modes; enum drm_connector_status status; struct list_head probed_modes; struct drm_display_info display_info; const struct drm_connector_funcs *funcs; struct drm_property_blob *edid_blob_ptr; struct drm_object_properties properties; struct drm_property *scaling_mode_property; struct drm_property_blob *path_blob_ptr; struct drm_property_blob *tile_blob_ptr; #define DRM_CONNECTOR_POLL_HPD (1 << 0); #define DRM_CONNECTOR_POLL_CONNECT (1 << 1); #define DRM_CONNECTOR_POLL_DISCONNECT (1 << 2); uint8_t polled; int dpms; const struct drm_connector_helper_funcs *helper_private; struct drm_cmdline_mode cmdline_mode; enum drm_connector_force force; bool override_edid; #define DRM_CONNECTOR_MAX_ENCODER 3; uint32_t encoder_ids[DRM_CONNECTOR_MAX_ENCODER]; struct drm_encoder *encoder; #define MAX_ELD_BYTES 128; uint8_t eld[MAX_ELD_BYTES]; bool latency_present[2]; int video_latency[2]; int audio_latency[2]; int null_edid_counter; unsigned bad_edid_counter; bool edid_corrupt; struct dentry *debugfs_entry; struct drm_connector_state *state; bool has_tile; struct drm_tile_group *tile_group; bool tile_is_single_monitor; uint8_t num_h_tile, num_v_tile; uint8_t tile_h_loc, tile_v_loc; uint16_t tile_h_size, tile_v_size; struct llist_node free_node; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>parent DRM device</dd> <dt><code class="docutils literal">kdev</code></dt> <dd>kernel device for sysfs attributes</dd> <dt><code class="docutils literal">attr</code></dt> <dd>sysfs attributes</dd> <dt><code class="docutils literal">head</code></dt> <dd>list management</dd> <dt><code class="docutils literal">base</code></dt> <dd>base KMS object</dd> <dt><code class="docutils literal">name</code></dt> <dd>human readable name, can be overwritten by the driver</dd> <dt><code class="docutils literal">mutex</code></dt> <dd>Lock for general connector state, but currently only protects registered. Most of the connector state is still protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>.</dd> <dt><code class="docutils literal">index</code></dt> <dd>Compacted connector index, which matches the position inside the mode_config.list for drivers not supporting hot-add/removing. Can be used as an array index. It is invariant over the lifetime of the connector.</dd> <dt><code class="docutils literal">connector_type</code></dt> <dd>one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h</dd> <dt><code class="docutils literal">connector_type_id</code></dt> <dd>index into connector type enum</dd> <dt><code class="docutils literal">interlace_allowed</code></dt> <dd>can this connector handle interlaced modes?</dd> <dt><code class="docutils literal">doublescan_allowed</code></dt> <dd>can this connector handle doublescan?</dd> <dt><code class="docutils literal">stereo_allowed</code></dt> <dd>can this connector handle stereo modes?</dd> <dt><code class="docutils literal">ycbcr_420_allowed</code></dt> <dd>This bool indicates if this connector is capable of handling YCBCR 420 output. While parsing the EDID blocks, its very helpful to know, if the source is capable of handling YCBCR 420 outputs.</dd> <dt><code class="docutils literal">registered</code></dt> <dd>Is this connector exposed (registered) with userspace? Protected by mutex.</dd> <dt><code class="docutils literal">modes</code></dt> <dd>Modes available on this connector (from <code class="xref c c-func docutils literal">fill_modes()</code> + user). Protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>.</dd> <dt><code class="docutils literal">status</code></dt> <dd>One of the drm_connector_status enums (connected, not, or unknown). Protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>.</dd> <dt><code class="docutils literal">probed_modes</code></dt> <dd>These are modes added by probing with DDC or the BIOS, before filtering is applied. Used by the probe helpers. Protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>.</dd> <dt><code class="docutils literal">display_info</code></dt> <dd>Display information is filled from EDID information when a display is detected. For non hot-pluggable displays such as flat panels in embedded systems, the driver should initialize the <a class="reference internal" href="#c.drm_display_info" title="drm_display_info"><code class="xref c c-type docutils literal">drm_display_info.width_mm</code></a> and <a class="reference internal" href="#c.drm_display_info" title="drm_display_info"><code class="xref c c-type docutils literal">drm_display_info.height_mm</code></a> fields with the physical size of the display. Protected by <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>. </dd> <dt><code class="docutils literal">funcs</code></dt> <dd>connector control functions</dd> <dt><code class="docutils literal">edid_blob_ptr</code></dt> <dd>DRM property containing EDID if present</dd> <dt><code class="docutils literal">properties</code></dt> <dd>property tracking for this connector</dd> <dt><code class="docutils literal">scaling_mode_property</code></dt> <dd>Optional atomic property to control the upscaling.</dd> <dt><code class="docutils literal">path_blob_ptr</code></dt> <dd>DRM blob property data for the DP MST path property.</dd> <dt><code class="docutils literal">tile_blob_ptr</code></dt> <dd>DRM blob property data for the tile property (used mostly by DP MST). This is meant for screens which are driven through separate display pipelines represented by <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>, which might not be running with genlocked clocks. For tiled panels which are genlocked, like dual-link LVDS or dual-link DSI, the driver should try to not expose the tiling and virtualize both <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> and <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> if needed.</dd> <dt><code class="docutils literal">polled</code></dt> <dd>Connector polling mode, a combination of <dl class="docutils"> <dt>DRM_CONNECTOR_POLL_HPD</dt> <dd>The connector generates hotplug events and doesn’t need to be periodically polled. The CONNECT and DISCONNECT flags must not be set together with the HPD flag.</dd> <dt>DRM_CONNECTOR_POLL_CONNECT</dt> <dd>Periodically poll the connector for connection.</dd> <dt>DRM_CONNECTOR_POLL_DISCONNECT</dt> <dd>Periodically poll the connector for disconnection.</dd> </dl> Set to 0 for connectors that don’t support connection status discovery. </dd> <dt><code class="docutils literal">dpms</code></dt> <dd>current dpms state</dd> <dt><code class="docutils literal">helper_private</code></dt> <dd>mid-layer private data</dd> <dt><code class="docutils literal">cmdline_mode</code></dt> <dd>mode line parsed from the kernel cmdline for this connector</dd> <dt><code class="docutils literal">force</code></dt> <dd>a DRM_FORCE_<foo> state for forced mode sets</dd> <dt><code class="docutils literal">override_edid</code></dt> <dd>has the EDID been overwritten through debugfs for testing?</dd> <dt><code class="docutils literal">encoder_ids</code></dt> <dd>valid encoders for this connector</dd> <dt><code class="docutils literal">encoder</code></dt> <dd>Currently bound encoder driving this connector, if any. Only really meaningful for non-atomic drivers. Atomic drivers should instead look at <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">drm_connector_state.best_encoder</code></a>, and in case they need the CRTC driving this output, <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">drm_connector_state.crtc</code></a>.</dd> <dt><code class="docutils literal">eld</code></dt> <dd>EDID-like data, if present</dd> <dt><code class="docutils literal">latency_present</code></dt> <dd>AV delay info from ELD, if found</dd> <dt><code class="docutils literal">video_latency</code></dt> <dd>video latency info from ELD, if found</dd> <dt><code class="docutils literal">audio_latency</code></dt> <dd>audio latency info from ELD, if found</dd> <dt><code class="docutils literal">null_edid_counter</code></dt> <dd>track sinks that give us all zeros for the EDID</dd> <dt><code class="docutils literal">bad_edid_counter</code></dt> <dd>track sinks that give us an EDID with invalid checksum</dd> <dt><code class="docutils literal">edid_corrupt</code></dt> <dd>indicates whether the last read EDID was corrupt</dd> <dt><code class="docutils literal">debugfs_entry</code></dt> <dd>debugfs directory for this connector</dd> <dt><code class="docutils literal">state</code></dt> <dd>Current atomic state for this connector. This is protected by drm_mode_config.connection_mutex. Note that nonblocking atomic commits access the current connector state without taking locks. Either by going through the <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state"><code class="xref c c-type docutils literal">struct drm_atomic_state</code></a> pointers, see <a class="reference internal" href="#c.for_each_oldnew_connector_in_state" title="for_each_oldnew_connector_in_state"><code class="xref c c-func docutils literal">for_each_oldnew_connector_in_state()</code></a>, <a class="reference internal" href="#c.for_each_old_connector_in_state" title="for_each_old_connector_in_state"><code class="xref c c-func docutils literal">for_each_old_connector_in_state()</code></a> and <a class="reference internal" href="#c.for_each_new_connector_in_state" title="for_each_new_connector_in_state"><code class="xref c c-func docutils literal">for_each_new_connector_in_state()</code></a>. Or through careful ordering of atomic commit operations as implemented in the atomic helpers, see <a class="reference internal" href="#c.drm_crtc_commit" title="drm_crtc_commit"><code class="xref c c-type docutils literal">struct drm_crtc_commit</code></a>. </dd> <dt><code class="docutils literal">has_tile</code></dt> <dd>is this connector connected to a tiled monitor</dd> <dt><code class="docutils literal">tile_group</code></dt> <dd>tile group for the connected monitor</dd> <dt><code class="docutils literal">tile_is_single_monitor</code></dt> <dd>whether the tile is one monitor housing</dd> <dt><code class="docutils literal">num_h_tile</code></dt> <dd>number of horizontal tiles in the tile group</dd> <dt><code class="docutils literal">num_v_tile</code></dt> <dd>number of vertical tiles in the tile group</dd> <dt><code class="docutils literal">tile_h_loc</code></dt> <dd>horizontal location of this tile</dd> <dt><code class="docutils literal">tile_v_loc</code></dt> <dd>vertical location of this tile</dd> <dt><code class="docutils literal">tile_h_size</code></dt> <dd>horizontal size of this tile.</dd> <dt><code class="docutils literal">tile_v_size</code></dt> <dd>vertical size of this tile.</dd> <dt><code class="docutils literal">free_node</code></dt> <dd>List used only by <code class="xref c c-type docutils literal">drm_connector_iter</code> to be able to clean up a connector from any context, in conjunction with <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.connector_free_work</code></a>.</dd> </dl> Description Each connector may be connected to one or more CRTCs, or may be clonable by another connector if they can share a CRTC. Each connector also has a specific position in the broader display (referred to as a ‘screen’ though it could span multiple monitors). <dl class="function"> <dt id="c.drm_connector_lookup"> struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * <code class="descname">drm_connector_lookup</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_connector_lookup" title="Permalink to this definition">¶</a></dt> <dd>lookup connector object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>connector object id</dd> </dl> Description This function looks up the connector object specified by id add takes a reference to it. <dl class="function"> <dt id="c.drm_connector_get"> void <code class="descname">drm_connector_get</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_get" title="Permalink to this definition">¶</a></dt> <dd>acquire a connector reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>DRM connector</dd> </dl> Description This function increments the connector’s refcount. <dl class="function"> <dt id="c.drm_connector_put"> void <code class="descname">drm_connector_put</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_put" title="Permalink to this definition">¶</a></dt> <dd>release a connector reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>DRM connector</dd> </dl> Description This function decrements the connector’s reference count and frees the object if the reference count drops to zero. <dl class="function"> <dt id="c.drm_connector_reference"> void <code class="descname">drm_connector_reference</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_reference" title="Permalink to this definition">¶</a></dt> <dd>acquire a connector reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>DRM connector</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_connector_get" title="drm_connector_get"><code class="xref c c-func docutils literal">drm_connector_get()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_connector_unreference"> void <code class="descname">drm_connector_unreference</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_unreference" title="Permalink to this definition">¶</a></dt> <dd>release a connector reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>DRM connector</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_connector_put" title="drm_connector_put"><code class="xref c c-func docutils literal">drm_connector_put()</code></a> and should not be used by new code. <dl class="type"> <dt id="c.drm_tile_group"> struct <code class="descname">drm_tile_group</code><a class="headerlink" href="#c.drm_tile_group" title="Permalink to this definition">¶</a></dt> <dd>Tile group metadata </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_tile_group { struct kref refcount; struct drm_device *dev; int id; u8 group_data[8]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">refcount</code></dt> <dd>reference count</dd> <dt><code class="docutils literal">dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">id</code></dt> <dd>tile group id exposed to userspace</dd> <dt><code class="docutils literal">group_data</code></dt> <dd>Sink-private data identifying this group</dd> </dl> Description group_data corresponds to displayid vend/prod/serial for external screens with an EDID. <dl class="type"> <dt id="c.drm_connector_list_iter"> struct <code class="descname">drm_connector_list_iter</code><a class="headerlink" href="#c.drm_connector_list_iter" title="Permalink to this definition">¶</a></dt> <dd>connector_list iterator </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_connector_list_iter { }; </pre></div> </div> Members Description This iterator tracks state needed to be able to walk the connector_list within struct drm_mode_config. Only use together with <a class="reference internal" href="#c.drm_connector_list_iter_begin" title="drm_connector_list_iter_begin"><code class="xref c c-func docutils literal">drm_connector_list_iter_begin()</code></a>, <a class="reference internal" href="#c.drm_connector_list_iter_end" title="drm_connector_list_iter_end"><code class="xref c c-func docutils literal">drm_connector_list_iter_end()</code></a> and <a class="reference internal" href="#c.drm_connector_list_iter_next" title="drm_connector_list_iter_next"><code class="xref c c-func docutils literal">drm_connector_list_iter_next()</code></a> respectively the convenience macro <a class="reference internal" href="#c.drm_for_each_connector_iter" title="drm_for_each_connector_iter"><code class="xref c c-func docutils literal">drm_for_each_connector_iter()</code></a>. <dl class="function"> <dt id="c.drm_for_each_connector_iter"> <code class="descname">drm_for_each_connector_iter</code>(connector, iter)<a class="headerlink" href="#c.drm_for_each_connector_iter" title="Permalink to this definition">¶</a></dt> <dd>connector_list iterator macro </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">connector</code></dt> <dd><a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a> pointer used as cursor</dd> <dt><code class="docutils literal">iter</code></dt> <dd><a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter"><code class="xref c c-type docutils literal">struct drm_connector_list_iter</code></a></dd> </dl> Description Note that connector is only valid within the list body, if you want to use connector after calling <a class="reference internal" href="#c.drm_connector_list_iter_end" title="drm_connector_list_iter_end"><code class="xref c c-func docutils literal">drm_connector_list_iter_end()</code></a> then you need to grab your own reference first using <a class="reference internal" href="#c.drm_connector_get" title="drm_connector_get"><code class="xref c c-func docutils literal">drm_connector_get()</code></a>. <dl class="function"> <dt id="c.drm_connector_init"> int <code class="descname">drm_connector_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, const struct <a class="reference internal" href="#c.drm_connector_funcs" title="drm_connector_funcs">drm_connector_funcs</a> * funcs, int connector_type)<a class="headerlink" href="#c.drm_connector_init" title="Permalink to this definition">¶</a></dt> <dd>Init a preallocated connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>the connector to init</dd> <dt><code class="docutils literal">const struct drm_connector_funcs * funcs</code></dt> <dd>callbacks for this connector</dd> <dt><code class="docutils literal">int connector_type</code></dt> <dd>user visible type of the connector</dd> </dl> Description Initialises a preallocated connector. Connectors should be subclassed as part of driver connector objects. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_mode_connector_attach_encoder"> int <code class="descname">drm_mode_connector_attach_encoder</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * encoder)<a class="headerlink" href="#c.drm_mode_connector_attach_encoder" title="Permalink to this definition">¶</a></dt> <dd>attach a connector to an encoder </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to attach</dd> <dt><code class="docutils literal">struct drm_encoder * encoder</code></dt> <dd>encoder to attach connector to</dd> </dl> Description This function links up a connector to an encoder. Note that the routing restrictions between encoders and crtcs are exposed to userspace through the possible_clones and possible_crtcs bitmasks. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_connector_cleanup"> void <code class="descname">drm_connector_cleanup</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_cleanup" title="Permalink to this definition">¶</a></dt> <dd>cleans up an initialised connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to cleanup</dd> </dl> Description Cleans up the connector but doesn’t free the object. <dl class="function"> <dt id="c.drm_connector_register"> int <code class="descname">drm_connector_register</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_register" title="Permalink to this definition">¶</a></dt> <dd>register a connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>the connector to register</dd> </dl> Description Register userspace interfaces for a connector Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_connector_unregister"> void <code class="descname">drm_connector_unregister</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_connector_unregister" title="Permalink to this definition">¶</a></dt> <dd>unregister a connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>the connector to unregister</dd> </dl> Description Unregister userspace interfaces for a connector <dl class="function"> <dt id="c.drm_get_connector_status_name"> const char * <code class="descname">drm_get_connector_status_name</code>(enum <a class="reference internal" href="#c.drm_connector_status" title="drm_connector_status">drm_connector_status</a> status)<a class="headerlink" href="#c.drm_get_connector_status_name" title="Permalink to this definition">¶</a></dt> <dd>return a string for connector status </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">enum drm_connector_status status</code></dt> <dd>connector status to compute name of</dd> </dl> Description In contrast to the other drm_get_*_name functions this one here returns a const pointer and hence is threadsafe. <dl class="function"> <dt id="c.drm_connector_list_iter_begin"> void <code class="descname">drm_connector_list_iter_begin</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter">drm_connector_list_iter</a> * iter)<a class="headerlink" href="#c.drm_connector_list_iter_begin" title="Permalink to this definition">¶</a></dt> <dd>initialize a connector_list iterator </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_connector_list_iter * iter</code></dt> <dd>connector_list iterator</dd> </dl> Description Sets iter up to walk the <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.connector_list</code></a> of dev. iter must always be cleaned up again by calling <a class="reference internal" href="#c.drm_connector_list_iter_end" title="drm_connector_list_iter_end"><code class="xref c c-func docutils literal">drm_connector_list_iter_end()</code></a>. Iteration itself happens using <a class="reference internal" href="#c.drm_connector_list_iter_next" title="drm_connector_list_iter_next"><code class="xref c c-func docutils literal">drm_connector_list_iter_next()</code></a> or <a class="reference internal" href="#c.drm_for_each_connector_iter" title="drm_for_each_connector_iter"><code class="xref c c-func docutils literal">drm_for_each_connector_iter()</code></a>. <dl class="function"> <dt id="c.drm_connector_list_iter_next"> struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * <code class="descname">drm_connector_list_iter_next</code>(struct <a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter">drm_connector_list_iter</a> * iter)<a class="headerlink" href="#c.drm_connector_list_iter_next" title="Permalink to this definition">¶</a></dt> <dd>return next connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector_list_iter * iter</code></dt> <dd>connectr_list iterator</dd> </dl> Description Returns the next connector for iter, or NULL when the list walk has completed. <dl class="function"> <dt id="c.drm_connector_list_iter_end"> void <code class="descname">drm_connector_list_iter_end</code>(struct <a class="reference internal" href="#c.drm_connector_list_iter" title="drm_connector_list_iter">drm_connector_list_iter</a> * iter)<a class="headerlink" href="#c.drm_connector_list_iter_end" title="Permalink to this definition">¶</a></dt> <dd>tear down a connector_list iterator </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector_list_iter * iter</code></dt> <dd>connector_list iterator</dd> </dl> Description Tears down iter and releases any resources (like <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a> references) acquired while walking the list. This must always be called, both when the iteration completes fully or when it was aborted without walking the entire list. <dl class="function"> <dt id="c.drm_get_subpixel_order_name"> const char * <code class="descname">drm_get_subpixel_order_name</code>(enum subpixel_order order)<a class="headerlink" href="#c.drm_get_subpixel_order_name" title="Permalink to this definition">¶</a></dt> <dd>return a string for a given subpixel enum </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">enum subpixel_order order</code></dt> <dd>enum of subpixel_order</dd> </dl> Description Note you could abuse this and return something out of bounds, but that would be a caller error. No unscrubbed user data should make it here. <dl class="function"> <dt id="c.drm_display_info_set_bus_formats"> int <code class="descname">drm_display_info_set_bus_formats</code>(struct <a class="reference internal" href="#c.drm_display_info" title="drm_display_info">drm_display_info</a> * info, const u32 * formats, unsigned int num_formats)<a class="headerlink" href="#c.drm_display_info_set_bus_formats" title="Permalink to this definition">¶</a></dt> <dd>set the supported bus formats </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_display_info * info</code></dt> <dd>display info to store bus formats in</dd> <dt><code class="docutils literal">const u32 * formats</code></dt> <dd>array containing the supported bus formats</dd> <dt><code class="docutils literal">unsigned int num_formats</code></dt> <dd>the number of entries in the fmts array</dd> </dl> Description Store the supported bus formats in display info structure. See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for a full list of available formats. <dl class="function"> <dt id="c.drm_mode_create_dvi_i_properties"> int <code class="descname">drm_mode_create_dvi_i_properties</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_create_dvi_i_properties" title="Permalink to this definition">¶</a></dt> <dd>create DVI-I specific connector properties </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Called by a driver the first time a DVI-I connector is made. <dl class="function"> <dt id="c.drm_mode_create_tv_properties"> int <code class="descname">drm_mode_create_tv_properties</code>(struct drm_device * dev, unsigned int num_modes, const char *const modes)<a class="headerlink" href="#c.drm_mode_create_tv_properties" title="Permalink to this definition">¶</a></dt> <dd>create TV specific connector properties </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">unsigned int num_modes</code></dt> <dd>number of different TV formats (modes) supported</dd> <dt><code class="docutils literal">const char *const modes</code></dt> <dd>array of pointers to strings containing name of each format</dd> </dl> Description Called by a driver’s TV initialization routine, this function creates the TV specific connector properties for a given device. Caller is responsible for allocating a list of format names and passing them to this routine. <dl class="function"> <dt id="c.drm_mode_create_scaling_mode_property"> int <code class="descname">drm_mode_create_scaling_mode_property</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_create_scaling_mode_property" title="Permalink to this definition">¶</a></dt> <dd>create scaling mode property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Called by a driver the first time it’s needed, must be attached to desired connectors. Atomic drivers should use <a class="reference internal" href="#c.drm_connector_attach_scaling_mode_property" title="drm_connector_attach_scaling_mode_property"><code class="xref c c-func docutils literal">drm_connector_attach_scaling_mode_property()</code></a> instead to correctly assign <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">drm_connector_state.picture_aspect_ratio</code></a> in the atomic state. <dl class="function"> <dt id="c.drm_connector_attach_scaling_mode_property"> int <code class="descname">drm_connector_attach_scaling_mode_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, u32 scaling_mode_mask)<a class="headerlink" href="#c.drm_connector_attach_scaling_mode_property" title="Permalink to this definition">¶</a></dt> <dd>attach atomic scaling mode property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to attach scaling mode property on.</dd> <dt><code class="docutils literal">u32 scaling_mode_mask</code></dt> <dd>or’ed mask of BIT(<code class="docutils literal">DRM_MODE_SCALE_</code>*).</dd> </dl> Description This is used to add support for scaling mode to atomic drivers. The scaling mode will be set to <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">drm_connector_state.picture_aspect_ratio</code></a> and can be used from <a class="reference internal" href="drm-kms-helpers.html#c.drm_connector_helper_funcs" title="drm_connector_helper_funcs"><code class="xref c c-type docutils literal">drm_connector_helper_funcs->atomic_check</code></a> for validation. This is the atomic version of <a class="reference internal" href="#c.drm_mode_create_scaling_mode_property" title="drm_mode_create_scaling_mode_property"><code class="xref c c-func docutils literal">drm_mode_create_scaling_mode_property()</code></a>. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_mode_create_aspect_ratio_property"> int <code class="descname">drm_mode_create_aspect_ratio_property</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_create_aspect_ratio_property" title="Permalink to this definition">¶</a></dt> <dd>create aspect ratio property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Called by a driver the first time it’s needed, must be attached to desired connectors. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_mode_create_suggested_offset_properties"> int <code class="descname">drm_mode_create_suggested_offset_properties</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_mode_create_suggested_offset_properties" title="Permalink to this definition">¶</a></dt> <dd>create suggests offset properties </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description Create the the suggested x/y offset property for connectors. <dl class="function"> <dt id="c.drm_mode_connector_set_path_property"> int <code class="descname">drm_mode_connector_set_path_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, const char * path)<a class="headerlink" href="#c.drm_mode_connector_set_path_property" title="Permalink to this definition">¶</a></dt> <dd>set tile property on connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to set property on.</dd> <dt><code class="docutils literal">const char * path</code></dt> <dd>path to use for property; must not be NULL.</dd> </dl> Description This creates a property to expose to userspace to specify a connector path. This is mainly used for DisplayPort MST where connectors have a topology and we want to allow userspace to give them more meaningful names. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_mode_connector_set_tile_property"> int <code class="descname">drm_mode_connector_set_tile_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector)<a class="headerlink" href="#c.drm_mode_connector_set_tile_property" title="Permalink to this definition">¶</a></dt> <dd>set tile property on connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector to set property on.</dd> </dl> Description This looks up the tile information for a connector, and creates a property for userspace to parse if it exists. The property is of the form of 8 integers using ‘:’ as a separator. Return Zero on success, errno on failure. <dl class="function"> <dt id="c.drm_mode_connector_update_edid_property"> int <code class="descname">drm_mode_connector_update_edid_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, const struct edid * edid)<a class="headerlink" href="#c.drm_mode_connector_update_edid_property" title="Permalink to this definition">¶</a></dt> <dd>update the edid property of a connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>drm connector</dd> <dt><code class="docutils literal">const struct edid * edid</code></dt> <dd>new value of the edid property</dd> </dl> Description This function creates a new blob modeset object and assigns its id to the connector’s edid property. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_mode_connector_set_link_status_property"> void <code class="descname">drm_mode_connector_set_link_status_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, uint64_t link_status)<a class="headerlink" href="#c.drm_mode_connector_set_link_status_property" title="Permalink to this definition">¶</a></dt> <dd>Set link status property of a connector </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>drm connector</dd> <dt><code class="docutils literal">uint64_t link_status</code></dt> <dd>new value of link status property (0: Good, 1: Bad)</dd> </dl> Description In usual working scenario, this link status property will always be set to “GOOD”. If something fails during or after a mode set, the kernel driver may set this link status property to “BAD”. The caller then needs to send a hotplug uevent for userspace to re-check the valid modes through GET_CONNECTOR_IOCTL and retry modeset. Note Drivers cannot rely on userspace to support this property and issue a modeset. As such, they may choose to handle issues (like re-training a link) without userspace’s intervention. The reason for adding this property is to handle link training failures, but it is not limited to DP or link training. For example, if we implement asynchronous setcrtc, this property can be used to report any failures in that. <dl class="function"> <dt id="c.drm_connector_init_panel_orientation_property"> int <code class="descname">drm_connector_init_panel_orientation_property</code>(struct <a class="reference internal" href="#c.drm_connector" title="drm_connector">drm_connector</a> * connector, int width, int height)<a class="headerlink" href="#c.drm_connector_init_panel_orientation_property" title="Permalink to this definition">¶</a></dt> <dd>initialize the connecters panel_orientation property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_connector * connector</code></dt> <dd>connector for which to init the panel-orientation property.</dd> <dt><code class="docutils literal">int width</code></dt> <dd>width in pixels of the panel, used for panel quirk detection</dd> <dt><code class="docutils literal">int height</code></dt> <dd>height in pixels of the panel, used for panel quirk detection</dd> </dl> Description This function should only be called for built-in panels, after setting connector->display_info.panel_orientation first (if known). This function will check for platform specific (e.g. DMI based) quirks overriding display_info.panel_orientation first, then if panel_orientation is not DRM_MODE_PANEL_ORIENTATION_UNKNOWN it will attach the “panel orientation” property to the connector. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_mode_put_tile_group"> void <code class="descname">drm_mode_put_tile_group</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_tile_group" title="drm_tile_group">drm_tile_group</a> * tg)<a class="headerlink" href="#c.drm_mode_put_tile_group" title="Permalink to this definition">¶</a></dt> <dd>drop a reference to a tile group. </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_tile_group * tg</code></dt> <dd>tile group to drop reference to.</dd> </dl> Description drop reference to tile group and free if 0. <dl class="function"> <dt id="c.drm_mode_get_tile_group"> struct <a class="reference internal" href="#c.drm_tile_group" title="drm_tile_group">drm_tile_group</a> * <code class="descname">drm_mode_get_tile_group</code>(struct drm_device * dev, char topology)<a class="headerlink" href="#c.drm_mode_get_tile_group" title="Permalink to this definition">¶</a></dt> <dd>get a reference to an existing tile group </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">char topology</code></dt> <dd>8-bytes unique per monitor.</dd> </dl> Description Use the unique bytes to get a reference to an existing tile group. Return tile group or NULL if not found. <dl class="function"> <dt id="c.drm_mode_create_tile_group"> struct <a class="reference internal" href="#c.drm_tile_group" title="drm_tile_group">drm_tile_group</a> * <code class="descname">drm_mode_create_tile_group</code>(struct drm_device * dev, char topology)<a class="headerlink" href="#c.drm_mode_create_tile_group" title="Permalink to this definition">¶</a></dt> <dd>create a tile group from a displayid description </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">char topology</code></dt> <dd>8-bytes unique per monitor.</dd> </dl> Description Create a tile group for the unique monitor, and get a unique identifier for the tile group. Return new tile group or error. </div> </div> <div class="section" id="encoder-abstraction"> <h2>Encoder Abstraction<a class="headerlink" href="#encoder-abstraction" title="Permalink to this headline">¶</a></h2> Encoders represent the connecting element between the CRTC (as the overall pixel pipeline, represented by <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>) and the connectors (as the generic sink entity, represented by <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">struct drm_connector</code></a>). An encoder takes pixel data from a CRTC and converts it to a format suitable for any attached connector. Encoders are objects exposed to userspace, originally to allow userspace to infer cloning and connector/CRTC restrictions. Unfortunately almost all drivers get this wrong, making the uabi pretty much useless. On top of that the exposed restrictions are too simple for today’s hardware, and the recommended way to infer restrictions is by using the DRM_MODE_ATOMIC_TEST_ONLY flag for the atomic IOCTL. Otherwise encoders aren’t used in the uapi at all (any modeset request from userspace directly connects a connector with a CRTC), drivers are therefore free to use them however they wish. Modeset helper libraries make strong use of encoders to facilitate code sharing. But for more complex settings it is usually better to move shared code into a separate <a class="reference internal" href="drm-kms-helpers.html#c.drm_bridge" title="drm_bridge"><code class="xref c c-type docutils literal">drm_bridge</code></a>. Compared to encoders, bridges also have the benefit of being purely an internal abstraction since they are not exposed to userspace at all. Encoders are initialized with <a class="reference internal" href="#c.drm_encoder_init" title="drm_encoder_init"><code class="xref c c-func docutils literal">drm_encoder_init()</code></a> and cleaned up using <a class="reference internal" href="#c.drm_encoder_cleanup" title="drm_encoder_cleanup"><code class="xref c c-func docutils literal">drm_encoder_cleanup()</code></a>. <div class="section" id="encoder-functions-reference"> <h3>Encoder Functions Reference<a class="headerlink" href="#encoder-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_encoder_funcs"> struct <code class="descname">drm_encoder_funcs</code><a class="headerlink" href="#c.drm_encoder_funcs" title="Permalink to this definition">¶</a></dt> <dd>encoder controls </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_encoder_funcs { void (*reset)(struct drm_encoder *encoder); void (*destroy)(struct drm_encoder *encoder); int (*late_register)(struct drm_encoder *encoder); void (*early_unregister)(struct drm_encoder *encoder); }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">reset</code></dt> <dd>Reset encoder hardware and software state to off. This function isn’t called by the core directly, only through <a class="reference internal" href="#c.drm_mode_config_reset" title="drm_mode_config_reset"><code class="xref c c-func docutils literal">drm_mode_config_reset()</code></a>. It’s not a helper hook only for historical reasons.</dd> <dt><code class="docutils literal">destroy</code></dt> <dd>Clean up encoder resources. This is only called at driver unload time through <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a> since an encoder cannot be hotplugged in DRM.</dd> <dt><code class="docutils literal">late_register</code></dt> <dd>This optional hook can be used to register additional userspace interfaces attached to the encoder like debugfs interfaces. It is called late in the driver load sequence from <a class="reference internal" href="drm-internals.html#c.drm_dev_register" title="drm_dev_register"><code class="xref c c-func docutils literal">drm_dev_register()</code></a>. Everything added from this callback should be unregistered in the early_unregister callback. Returns: 0 on success, or a negative error code on failure. </dd> <dt><code class="docutils literal">early_unregister</code></dt> <dd>This optional hook should be used to unregister the additional userspace interfaces attached to the encoder from late_register. It is called from <a class="reference internal" href="drm-internals.html#c.drm_dev_unregister" title="drm_dev_unregister"><code class="xref c c-func docutils literal">drm_dev_unregister()</code></a>, early in the driver unload sequence to disable userspace access before data structures are torndown.</dd> </dl> Description Encoders sit between CRTCs and connectors. <dl class="type"> <dt id="c.drm_encoder"> struct <code class="descname">drm_encoder</code><a class="headerlink" href="#c.drm_encoder" title="Permalink to this definition">¶</a></dt> <dd>central DRM encoder structure </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_encoder { struct drm_device *dev; struct list_head head; struct drm_mode_object base; char *name; int encoder_type; unsigned index; uint32_t possible_crtcs; uint32_t possible_clones; struct drm_crtc *crtc; struct drm_bridge *bridge; const struct drm_encoder_funcs *funcs; const struct drm_encoder_helper_funcs *helper_private; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>parent DRM device</dd> <dt><code class="docutils literal">head</code></dt> <dd>list management</dd> <dt><code class="docutils literal">base</code></dt> <dd>base KMS object</dd> <dt><code class="docutils literal">name</code></dt> <dd>human readable name, can be overwritten by the driver</dd> <dt><code class="docutils literal">encoder_type</code></dt> <dd>One of the DRM_MODE_ENCODER_<foo> types in drm_mode.h. The following encoder types are defined thus far: <ul class="last simple"> <li>DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A.</li> <li>DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort.</li> <li>DRM_MODE_ENCODER_LVDS for display panels, or in general any panel with a proprietary parallel connector.</li> <li>DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, SCART).</li> <li>DRM_MODE_ENCODER_VIRTUAL for virtual machine displays</li> <li>DRM_MODE_ENCODER_DSI for panels connected using the DSI serial bus.</li> <li>DRM_MODE_ENCODER_DPI for panels connected using the DPI parallel bus.</li> <li>DRM_MODE_ENCODER_DPMST for special fake encoders used to allow mutliple DP MST streams to share one physical encoder.</li> </ul> </dd> <dt><code class="docutils literal">index</code></dt> <dd>Position inside the mode_config.list, can be used as an array index. It is invariant over the lifetime of the encoder.</dd> <dt><code class="docutils literal">possible_crtcs</code></dt> <dd>Bitmask of potential CRTC bindings, using <a class="reference internal" href="#c.drm_crtc_index" title="drm_crtc_index"><code class="xref c c-func docutils literal">drm_crtc_index()</code></a> as the index into the bitfield. The driver must set the bits for all <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> objects this encoder can be connected to before calling <a class="reference internal" href="#c.drm_encoder_init" title="drm_encoder_init"><code class="xref c c-func docutils literal">drm_encoder_init()</code></a>. In reality almost every driver gets this wrong. Note that since CRTC objects can’t be hotplugged the assigned indices are stable and hence known before registering all objects. </dd> <dt><code class="docutils literal">possible_clones</code></dt> <dd>Bitmask of potential sibling encoders for cloning, using <a class="reference internal" href="#c.drm_encoder_index" title="drm_encoder_index"><code class="xref c c-func docutils literal">drm_encoder_index()</code></a> as the index into the bitfield. The driver must set the bits for all <a class="reference internal" href="#c.drm_encoder" title="drm_encoder"><code class="xref c c-type docutils literal">drm_encoder</code></a> objects which can clone a <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> together with this encoder before calling <a class="reference internal" href="#c.drm_encoder_init" title="drm_encoder_init"><code class="xref c c-func docutils literal">drm_encoder_init()</code></a>. Drivers should set the bit representing the encoder itself, too. Cloning bits should be set such that when two encoders can be used in a cloned configuration, they both should have each another bits set. In reality almost every driver gets this wrong. Note that since encoder objects can’t be hotplugged the assigned indices are stable and hence known before registering all objects. </dd> <dt><code class="docutils literal">crtc</code></dt> <dd>Currently bound CRTC, only really meaningful for non-atomic drivers. Atomic drivers should instead check <a class="reference internal" href="#c.drm_connector_state" title="drm_connector_state"><code class="xref c c-type docutils literal">drm_connector_state.crtc</code></a>.</dd> <dt><code class="docutils literal">bridge</code></dt> <dd>bridge associated to the encoder</dd> <dt><code class="docutils literal">funcs</code></dt> <dd>control functions</dd> <dt><code class="docutils literal">helper_private</code></dt> <dd>mid-layer private data</dd> </dl> Description CRTCs drive pixels to encoders, which convert them into signals appropriate for a given connector or set of connectors. <dl class="function"> <dt id="c.drm_encoder_index"> unsigned int <code class="descname">drm_encoder_index</code>(struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * encoder)<a class="headerlink" href="#c.drm_encoder_index" title="Permalink to this definition">¶</a></dt> <dd>find the index of a registered encoder </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_encoder * encoder</code></dt> <dd>encoder to find index for</dd> </dl> Description Given a registered encoder, return the index of that encoder within a DRM device’s list of encoders. <dl class="function"> <dt id="c.drm_encoder_crtc_ok"> bool <code class="descname">drm_encoder_crtc_ok</code>(struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * encoder, struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_encoder_crtc_ok" title="Permalink to this definition">¶</a></dt> <dd>can a given crtc drive a given encoder? </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_encoder * encoder</code></dt> <dd>encoder to test</dd> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>crtc to test</dd> </dl> Description Returns false if encoder can’t be driven by crtc, true otherwise. <dl class="function"> <dt id="c.drm_encoder_find"> struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * <code class="descname">drm_encoder_find</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_encoder_find" title="Permalink to this definition">¶</a></dt> <dd>find a <a class="reference internal" href="#c.drm_encoder" title="drm_encoder"><code class="xref c c-type docutils literal">drm_encoder</code></a> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>encoder id</dd> </dl> Description Returns the encoder with id, NULL if it doesn’t exist. Simple wrapper around <a class="reference internal" href="#c.drm_mode_object_find" title="drm_mode_object_find"><code class="xref c c-func docutils literal">drm_mode_object_find()</code></a>. <dl class="function"> <dt id="c.drm_for_each_encoder_mask"> <code class="descname">drm_for_each_encoder_mask</code>(encoder, dev, encoder_mask)<a class="headerlink" href="#c.drm_for_each_encoder_mask" title="Permalink to this definition">¶</a></dt> <dd>iterate over encoders specified by bitmask </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">encoder</code></dt> <dd>the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the DRM device</dd> <dt><code class="docutils literal">encoder_mask</code></dt> <dd>bitmask of encoder indices</dd> </dl> Description Iterate over all encoders specified by bitmask. <dl class="function"> <dt id="c.drm_for_each_encoder"> <code class="descname">drm_for_each_encoder</code>(encoder, dev)<a class="headerlink" href="#c.drm_for_each_encoder" title="Permalink to this definition">¶</a></dt> <dd>iterate over all encoders </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">encoder</code></dt> <dd>the loop cursor</dd> <dt><code class="docutils literal">dev</code></dt> <dd>the DRM device</dd> </dl> Description Iterate over all encoders of dev. <dl class="function"> <dt id="c.drm_encoder_init"> int <code class="descname">drm_encoder_init</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * encoder, const struct <a class="reference internal" href="#c.drm_encoder_funcs" title="drm_encoder_funcs">drm_encoder_funcs</a> * funcs, int encoder_type, const char * name, ...)<a class="headerlink" href="#c.drm_encoder_init" title="Permalink to this definition">¶</a></dt> <dd>Init a preallocated encoder </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">struct drm_encoder * encoder</code></dt> <dd>the encoder to init</dd> <dt><code class="docutils literal">const struct drm_encoder_funcs * funcs</code></dt> <dd>callbacks for this encoder</dd> <dt><code class="docutils literal">int encoder_type</code></dt> <dd>user visible type of the encoder</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>printf style format string for the encoder name, or NULL for default name</dd> <dt><code class="docutils literal">...</code></dt> <dd>variable arguments</dd> </dl> Description Initialises a preallocated encoder. Encoder should be subclassed as part of driver encoder objects. At driver unload time <a class="reference internal" href="#c.drm_encoder_cleanup" title="drm_encoder_cleanup"><code class="xref c c-func docutils literal">drm_encoder_cleanup()</code></a> should be called from the driver’s <a class="reference internal" href="#c.drm_encoder_funcs" title="drm_encoder_funcs"><code class="xref c c-type docutils literal">drm_encoder_funcs.destroy</code></a> hook. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_encoder_cleanup"> void <code class="descname">drm_encoder_cleanup</code>(struct <a class="reference internal" href="#c.drm_encoder" title="drm_encoder">drm_encoder</a> * encoder)<a class="headerlink" href="#c.drm_encoder_cleanup" title="Permalink to this definition">¶</a></dt> <dd>cleans up an initialised encoder </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_encoder * encoder</code></dt> <dd>encoder to cleanup</dd> </dl> Description Cleans up the encoder but doesn’t free the object. </div> </div> <div class="section" id="kms-initialization-and-cleanup"> <h2>KMS Initialization and Cleanup<a class="headerlink" href="#kms-initialization-and-cleanup" title="Permalink to this headline">¶</a></h2> A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders and connectors. KMS drivers must thus create and initialize all those objects at load time after initializing mode setting. <div class="section" id="crtcs-struct-drm-crtc"> <h3>CRTCs (<a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>)<a class="headerlink" href="#crtcs-struct-drm-crtc" title="Permalink to this headline">¶</a></h3> A CRTC is an abstraction representing a part of the chip that contains a pointer to a scanout buffer. Therefore, the number of CRTCs available determines how many independent scanout buffers can be active at any given time. The CRTC structure contains several fields to support this: a pointer to some video memory (abstracted as a frame buffer object), a display mode, and an (x, y) offset into the video memory to support panning or configurations where one piece of video memory spans multiple CRTCs. <div class="section" id="crtc-initialization"> <h4>CRTC Initialization<a class="headerlink" href="#crtc-initialization" title="Permalink to this headline">¶</a></h4> A KMS device must create and register at least one struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> instance. The instance is allocated and zeroed by the driver, possibly as part of a larger structure, and registered with a call to <a class="reference internal" href="drm-kms-helpers.html#c.drm_crtc_init" title="drm_crtc_init"><code class="xref c c-func docutils literal">drm_crtc_init()</code></a> with a pointer to CRTC functions. </div> </div> <div class="section" id="cleanup"> <h3>Cleanup<a class="headerlink" href="#cleanup" title="Permalink to this headline">¶</a></h3> The DRM core manages its objects’ lifetime. When an object is not needed anymore the core calls its destroy function, which must clean up and free every resource allocated for the object. Every <code class="xref c c-func docutils literal">drm_*_init()</code> call must be matched with a corresponding <code class="xref c c-func docutils literal">drm_*_cleanup()</code> call to cleanup CRTCs (<a class="reference internal" href="#c.drm_crtc_cleanup" title="drm_crtc_cleanup"><code class="xref c c-func docutils literal">drm_crtc_cleanup()</code></a>), planes (<a class="reference internal" href="#c.drm_plane_cleanup" title="drm_plane_cleanup"><code class="xref c c-func docutils literal">drm_plane_cleanup()</code></a>), encoders (<a class="reference internal" href="#c.drm_encoder_cleanup" title="drm_encoder_cleanup"><code class="xref c c-func docutils literal">drm_encoder_cleanup()</code></a>) and connectors (<a class="reference internal" href="#c.drm_connector_cleanup" title="drm_connector_cleanup"><code class="xref c c-func docutils literal">drm_connector_cleanup()</code></a>). Furthermore, connectors that have been added to sysfs must be removed by a call to <a class="reference internal" href="#c.drm_connector_unregister" title="drm_connector_unregister"><code class="xref c c-func docutils literal">drm_connector_unregister()</code></a> before calling <a class="reference internal" href="#c.drm_connector_cleanup" title="drm_connector_cleanup"><code class="xref c c-func docutils literal">drm_connector_cleanup()</code></a>. Connectors state change detection must be cleanup up with a call to <a class="reference internal" href="drm-kms-helpers.html#c.drm_kms_helper_poll_fini" title="drm_kms_helper_poll_fini"><code class="xref c c-func docutils literal">drm_kms_helper_poll_fini()</code></a>. </div> <div class="section" id="output-discovery-and-initialization-example"> <h3>Output discovery and initialization example<a class="headerlink" href="#output-discovery-and-initialization-example" title="Permalink to this headline">¶</a></h3> <div class="highlight-c"><div class="highlight"><pre>void intel_crt_init(struct drm_device *dev) { struct drm_connector *connector; struct intel_output *intel_output; intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); if (!intel_output) return; connector = &intel_output->base; drm_connector_init(dev, &intel_output->base, &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, DRM_MODE_ENCODER_DAC); drm_mode_connector_attach_encoder(&intel_output->base, &intel_output->enc); /* Set up the DDC bus. */ intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); if (!intel_output->ddc_bus) { dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " "failed.\n"); return; } intel_output->type = INTEL_OUTPUT_ANALOG; connector->interlace_allowed = 0; connector->doublescan_allowed = 0; drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); drm_connector_register(connector); } </pre></div> </div> In the example above (taken from the i915 driver), a CRTC, connector and encoder combination is created. A device-specific i2c bus is also created for fetching EDID data and performing monitor detection. Once the process is complete, the new connector is registered with sysfs to make its properties available to applications. </div> </div> <div class="section" id="kms-locking"> <h2>KMS Locking<a class="headerlink" href="#kms-locking" title="Permalink to this headline">¶</a></h2> As KMS moves toward more fine grained locking, and atomic ioctl where userspace can indirectly control locking order, it becomes necessary to use <code class="xref c c-type docutils literal">ww_mutex</code> and acquire-contexts to avoid deadlocks. But because the locking is more distributed around the driver code, we want a bit of extra utility/tracking out of our acquire-ctx. This is provided by <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-type docutils literal">struct drm_modeset_lock</code></a> and <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx"><code class="xref c c-type docutils literal">struct drm_modeset_acquire_ctx</code></a>. For basic principles of <code class="xref c c-type docutils literal">ww_mutex</code>, see: Documentation/locking/ww-mutex-design.txt The basic usage pattern is to: <div class="highlight-none"><div class="highlight"><pre>drm_modeset_acquire_init(ctx, DRM_MODESET_ACQUIRE_INTERRUPTIBLE) retry: foreach (lock in random_ordered_set_of_locks) { ret = drm_modeset_lock(lock, ctx) if (ret == -EDEADLK) { ret = drm_modeset_backoff(ctx); if (!ret) goto retry; } if (ret) goto out; } ... do stuff ... out: drm_modeset_drop_locks(ctx); drm_modeset_acquire_fini(ctx); </pre></div> </div> If all that is needed is a single modeset lock, then the <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx"><code class="xref c c-type docutils literal">struct drm_modeset_acquire_ctx</code></a> is not needed and the locking can be simplified by passing a NULL instead of ctx in the <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a> call or calling <a class="reference internal" href="#c.drm_modeset_lock_single_interruptible" title="drm_modeset_lock_single_interruptible"><code class="xref c c-func docutils literal">drm_modeset_lock_single_interruptible()</code></a>. To unlock afterwards call <a class="reference internal" href="#c.drm_modeset_unlock" title="drm_modeset_unlock"><code class="xref c c-func docutils literal">drm_modeset_unlock()</code></a>. On top of these per-object locks using <code class="xref c c-type docutils literal">ww_mutex</code> there’s also an overall <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a>, for protecting everything else. Mostly this means probe state of connectors, and preventing hotplug add/removal of connectors. Finally there’s a bunch of dedicated locks to protect drm core internal lists and lookup data structures. <dl class="type"> <dt id="c.drm_modeset_acquire_ctx"> struct <code class="descname">drm_modeset_acquire_ctx</code><a class="headerlink" href="#c.drm_modeset_acquire_ctx" title="Permalink to this definition">¶</a></dt> <dd>locking context (see ww_acquire_ctx) </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_modeset_acquire_ctx { struct ww_acquire_ctx ww_ctx; struct drm_modeset_lock *contended; struct list_head locked; bool trylock_only; bool interruptible; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">ww_ctx</code></dt> <dd>base acquire ctx</dd> <dt><code class="docutils literal">contended</code></dt> <dd>used internally for -EDEADLK handling</dd> <dt><code class="docutils literal">locked</code></dt> <dd>list of held locks</dd> <dt><code class="docutils literal">trylock_only</code></dt> <dd>trylock mode used in atomic contexts/panic notifiers</dd> <dt><code class="docutils literal">interruptible</code></dt> <dd>whether interruptible locking should be used.</dd> </dl> Description Each thread competing for a set of locks must use one acquire ctx. And if any lock fxn returns -EDEADLK, it must backoff and retry. <dl class="type"> <dt id="c.drm_modeset_lock"> struct <code class="descname">drm_modeset_lock</code><a class="headerlink" href="#c.drm_modeset_lock" title="Permalink to this definition">¶</a></dt> <dd>used for locking modeset resources. </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_modeset_lock { struct ww_mutex mutex; struct list_head head; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">mutex</code></dt> <dd>resource locking</dd> <dt><code class="docutils literal">head</code></dt> <dd>used to hold it’s place on <code class="xref c c-type docutils literal">drm_atomi_state.locked</code> list when part of an atomic update</dd> </dl> Description Used for locking CRTCs and other modeset resources. <dl class="function"> <dt id="c.drm_modeset_lock_fini"> void <code class="descname">drm_modeset_lock_fini</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock)<a class="headerlink" href="#c.drm_modeset_lock_fini" title="Permalink to this definition">¶</a></dt> <dd>cleanup lock </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to cleanup</dd> </dl> <dl class="function"> <dt id="c.drm_modeset_is_locked"> bool <code class="descname">drm_modeset_is_locked</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock)<a class="headerlink" href="#c.drm_modeset_is_locked" title="Permalink to this definition">¶</a></dt> <dd>equivalent to <a class="reference internal" href="../kernel-hacking/locking.html#c.mutex_is_locked" title="mutex_is_locked"><code class="xref c c-func docutils literal">mutex_is_locked()</code></a> </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to check</dd> </dl> <dl class="function"> <dt id="c.drm_modeset_lock_all"> void <code class="descname">drm_modeset_lock_all</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_modeset_lock_all" title="Permalink to this definition">¶</a></dt> <dd>take all modeset locks </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description This function takes all modeset locks, suitable where a more fine-grained scheme isn’t (yet) implemented. Locks must be dropped by calling the <a class="reference internal" href="#c.drm_modeset_unlock_all" title="drm_modeset_unlock_all"><code class="xref c c-func docutils literal">drm_modeset_unlock_all()</code></a> function. This function is deprecated. It allocates a lock acquisition context and stores it in <code class="xref c c-type docutils literal">drm_device.mode_config</code>. This facilitate conversion of existing code because it removes the need to manually deal with the acquisition context, but it is also brittle because the context is global and care must be taken not to nest calls. New code should use the <a class="reference internal" href="#c.drm_modeset_lock_all_ctx" title="drm_modeset_lock_all_ctx"><code class="xref c c-func docutils literal">drm_modeset_lock_all_ctx()</code></a> function and pass in the context explicitly. <dl class="function"> <dt id="c.drm_modeset_unlock_all"> void <code class="descname">drm_modeset_unlock_all</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_modeset_unlock_all" title="Permalink to this definition">¶</a></dt> <dd>drop all modeset locks </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> </dl> Description This function drops all modeset locks taken by a previous call to the <a class="reference internal" href="#c.drm_modeset_lock_all" title="drm_modeset_lock_all"><code class="xref c c-func docutils literal">drm_modeset_lock_all()</code></a> function. This function is deprecated. It uses the lock acquisition context stored in <code class="xref c c-type docutils literal">drm_device.mode_config</code>. This facilitates conversion of existing code because it removes the need to manually deal with the acquisition context, but it is also brittle because the context is global and care must be taken not to nest calls. New code should pass the acquisition context directly to the <a class="reference internal" href="#c.drm_modeset_drop_locks" title="drm_modeset_drop_locks"><code class="xref c c-func docutils literal">drm_modeset_drop_locks()</code></a> function. <dl class="function"> <dt id="c.drm_warn_on_modeset_not_all_locked"> void <code class="descname">drm_warn_on_modeset_not_all_locked</code>(struct drm_device * dev)<a class="headerlink" href="#c.drm_warn_on_modeset_not_all_locked" title="Permalink to this definition">¶</a></dt> <dd>check that all modeset locks are locked </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>device</dd> </dl> Description Useful as a debug assert. <dl class="function"> <dt id="c.drm_modeset_acquire_init"> void <code class="descname">drm_modeset_acquire_init</code>(struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx, uint32_t flags)<a class="headerlink" href="#c.drm_modeset_acquire_init" title="Permalink to this definition">¶</a></dt> <dd>initialize acquire context </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>the acquire context</dd> <dt><code class="docutils literal">uint32_t flags</code></dt> <dd>0 or <code class="docutils literal">DRM_MODESET_ACQUIRE_INTERRUPTIBLE</code></dd> </dl> Description When passing <code class="docutils literal">DRM_MODESET_ACQUIRE_INTERRUPTIBLE</code> to flags, all calls to <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a> will perform an interruptible wait. <dl class="function"> <dt id="c.drm_modeset_acquire_fini"> void <code class="descname">drm_modeset_acquire_fini</code>(struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx)<a class="headerlink" href="#c.drm_modeset_acquire_fini" title="Permalink to this definition">¶</a></dt> <dd>cleanup acquire context </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>the acquire context</dd> </dl> <dl class="function"> <dt id="c.drm_modeset_drop_locks"> void <code class="descname">drm_modeset_drop_locks</code>(struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx)<a class="headerlink" href="#c.drm_modeset_drop_locks" title="Permalink to this definition">¶</a></dt> <dd>drop all locks </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>the acquire context</dd> </dl> Description Drop all locks currently held against this acquire context. <dl class="function"> <dt id="c.drm_modeset_backoff"> int <code class="descname">drm_modeset_backoff</code>(struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx)<a class="headerlink" href="#c.drm_modeset_backoff" title="Permalink to this definition">¶</a></dt> <dd>deadlock avoidance backoff </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>the acquire context</dd> </dl> Description If deadlock is detected (ie. <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a> returns -EDEADLK), you must call this function to drop all currently held locks and block until the contended lock becomes available. This function returns 0 on success, or -ERESTARTSYS if this context is initialized with <code class="docutils literal">DRM_MODESET_ACQUIRE_INTERRUPTIBLE</code> and the wait has been interrupted. <dl class="function"> <dt id="c.drm_modeset_lock_init"> void <code class="descname">drm_modeset_lock_init</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock)<a class="headerlink" href="#c.drm_modeset_lock_init" title="Permalink to this definition">¶</a></dt> <dd>initialize lock </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to init</dd> </dl> <dl class="function"> <dt> int <code class="descname">drm_modeset_lock</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock, struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx)</dt> <dd>take modeset lock </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to take</dd> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>acquire ctx</dd> </dl> Description If ctx is not NULL, then its ww acquire context is used and the lock will be tracked by the context and can be released by calling <a class="reference internal" href="#c.drm_modeset_drop_locks" title="drm_modeset_drop_locks"><code class="xref c c-func docutils literal">drm_modeset_drop_locks()</code></a>. If -EDEADLK is returned, this means a deadlock scenario has been detected and it is an error to attempt to take any more locks without first calling <a class="reference internal" href="#c.drm_modeset_backoff" title="drm_modeset_backoff"><code class="xref c c-func docutils literal">drm_modeset_backoff()</code></a>. If the ctx is not NULL and initialized with <code class="docutils literal">DRM_MODESET_ACQUIRE_INTERRUPTIBLE</code>, this function will fail with -ERESTARTSYS when interrupted. If ctx is NULL then the function call behaves like a normal, uninterruptible non-nesting <a class="reference internal" href="../kernel-hacking/locking.html#c.mutex_lock" title="mutex_lock"><code class="xref c c-func docutils literal">mutex_lock()</code></a> call. <dl class="function"> <dt id="c.drm_modeset_lock_single_interruptible"> int <code class="descname">drm_modeset_lock_single_interruptible</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock)<a class="headerlink" href="#c.drm_modeset_lock_single_interruptible" title="Permalink to this definition">¶</a></dt> <dd>take a single modeset lock </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to take</dd> </dl> Description This function behaves as <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock"><code class="xref c c-func docutils literal">drm_modeset_lock()</code></a> with a NULL context, but performs interruptible waits. This function returns 0 on success, or -ERESTARTSYS when interrupted. <dl class="function"> <dt id="c.drm_modeset_unlock"> void <code class="descname">drm_modeset_unlock</code>(struct <a class="reference internal" href="#c.drm_modeset_lock" title="drm_modeset_lock">drm_modeset_lock</a> * lock)<a class="headerlink" href="#c.drm_modeset_unlock" title="Permalink to this definition">¶</a></dt> <dd>drop modeset lock </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_modeset_lock * lock</code></dt> <dd>lock to release</dd> </dl> <dl class="function"> <dt id="c.drm_modeset_lock_all_ctx"> int <code class="descname">drm_modeset_lock_all_ctx</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_modeset_acquire_ctx" title="drm_modeset_acquire_ctx">drm_modeset_acquire_ctx</a> * ctx)<a class="headerlink" href="#c.drm_modeset_lock_all_ctx" title="Permalink to this definition">¶</a></dt> <dd>take all modeset locks </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_modeset_acquire_ctx * ctx</code></dt> <dd>lock acquisition context</dd> </dl> Description This function takes all modeset locks, suitable where a more fine-grained scheme isn’t (yet) implemented. Unlike <a class="reference internal" href="#c.drm_modeset_lock_all" title="drm_modeset_lock_all"><code class="xref c c-func docutils literal">drm_modeset_lock_all()</code></a>, it doesn’t take the <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.mutex</code></a> since that lock isn’t required for modeset state changes. Callers which need to grab that lock too need to do so outside of the acquire context ctx. Locks acquired with this function should be released by calling the <a class="reference internal" href="#c.drm_modeset_drop_locks" title="drm_modeset_drop_locks"><code class="xref c c-func docutils literal">drm_modeset_drop_locks()</code></a> function on ctx. Return 0 on success or a negative error-code on failure. </div> <div class="section" id="kms-properties"> <h2>KMS Properties<a class="headerlink" href="#kms-properties" title="Permalink to this headline">¶</a></h2> <div class="section" id="property-types-and-blob-property-support"> <h3>Property Types and Blob Property Support<a class="headerlink" href="#property-types-and-blob-property-support" title="Permalink to this headline">¶</a></h3> Properties as represented by <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a> are used to extend the modeset interface exposed to userspace. For the atomic modeset IOCTL properties are even the only way to transport metadata about the desired new modeset configuration from userspace to the kernel. Properties have a well-defined value range, which is enforced by the drm core. See the documentation of the flags member of <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">struct drm_property</code></a> for an overview of the different property types and ranges. Properties don’t store the current value directly, but need to be instatiated by attaching them to a <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object"><code class="xref c c-type docutils literal">drm_mode_object</code></a> with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. Property values are only 64bit. To support bigger piles of data (like gamma tables, color correction matrices or large structures) a property can instead point at a <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob"><code class="xref c c-type docutils literal">drm_property_blob</code></a> with that additional data. Properties are defined by their symbolic name, userspace must keep a per-object mapping from those names to the property ID used in the atomic IOCTL and in the get/set property IOCTL. <dl class="type"> <dt id="c.drm_property_enum"> struct <code class="descname">drm_property_enum</code><a class="headerlink" href="#c.drm_property_enum" title="Permalink to this definition">¶</a></dt> <dd>symbolic values for enumerations </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_property_enum { uint64_t value; struct list_head head; char name[DRM_PROP_NAME_LEN]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">value</code></dt> <dd>numeric property value for this enum entry</dd> <dt><code class="docutils literal">head</code></dt> <dd>list of enum values, linked to <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property.enum_list</code></a></dd> <dt><code class="docutils literal">name</code></dt> <dd>symbolic name for the enum</dd> </dl> Description For enumeration and bitmask properties this structure stores the symbolic decoding for each value. This is used for example for the rotation property. <dl class="type"> <dt id="c.drm_property"> struct <code class="descname">drm_property</code><a class="headerlink" href="#c.drm_property" title="Permalink to this definition">¶</a></dt> <dd>modeset object property </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_property { struct list_head head; struct drm_mode_object base; uint32_t flags; char name[DRM_PROP_NAME_LEN]; uint32_t num_values; uint64_t *values; struct drm_device *dev; struct list_head enum_list; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">head</code></dt> <dd>per-device list of properties, for cleanup.</dd> <dt><code class="docutils literal">base</code></dt> <dd>base KMS object</dd> <dt><code class="docutils literal">flags</code></dt> <dd>Property flags and type. A property needs to be one of the following types: <dl class="docutils"> <dt>DRM_MODE_PROP_RANGE</dt> <dd>Range properties report their minimum and maximum admissible unsigned values. The KMS core verifies that values set by application fit in that range. The range is unsigned. Range properties are created using <a class="reference internal" href="#c.drm_property_create_range" title="drm_property_create_range"><code class="xref c c-func docutils literal">drm_property_create_range()</code></a>.</dd> <dt>DRM_MODE_PROP_SIGNED_RANGE</dt> <dd>Range properties report their minimum and maximum admissible unsigned values. The KMS core verifies that values set by application fit in that range. The range is signed. Range properties are created using <a class="reference internal" href="#c.drm_property_create_signed_range" title="drm_property_create_signed_range"><code class="xref c c-func docutils literal">drm_property_create_signed_range()</code></a>.</dd> <dt>DRM_MODE_PROP_ENUM</dt> <dd>Enumerated properties take a numerical value that ranges from 0 to the number of enumerated values defined by the property minus one, and associate a free-formed string name to each value. Applications can retrieve the list of defined value-name pairs and use the numerical value to get and set property instance values. Enum properties are created using <a class="reference internal" href="#c.drm_property_create_enum" title="drm_property_create_enum"><code class="xref c c-func docutils literal">drm_property_create_enum()</code></a>.</dd> <dt>DRM_MODE_PROP_BITMASK</dt> <dd>Bitmask properties are enumeration properties that additionally restrict all enumerated values to the 0..63 range. Bitmask property instance values combine one or more of the enumerated bits defined by the property. Bitmask properties are created using <a class="reference internal" href="#c.drm_property_create_bitmask" title="drm_property_create_bitmask"><code class="xref c c-func docutils literal">drm_property_create_bitmask()</code></a>.</dd> <dt>DRM_MODE_PROB_OBJECT</dt> <dd>Object properties are used to link modeset objects. This is used extensively in the atomic support to create the display pipeline, by linking <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a> to <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a>, <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> to <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> and <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a> to <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>. An object property can only link to a specific type of <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object"><code class="xref c c-type docutils literal">drm_mode_object</code></a>, this limit is enforced by the core. Object properties are created using <a class="reference internal" href="#c.drm_property_create_object" title="drm_property_create_object"><code class="xref c c-func docutils literal">drm_property_create_object()</code></a>. Object properties work like blob properties, but in a more general fashion. They are limited to atomic drivers and must have the DRM_MODE_PROP_ATOMIC flag set. </dd> <dt>DRM_MODE_PROP_BLOB</dt> <dd>Blob properties store a binary blob without any format restriction. The binary blobs are created as KMS standalone objects, and blob property instance values store the ID of their associated blob object. Blob properties are created by calling <a class="reference internal" href="#c.drm_property_create" title="drm_property_create"><code class="xref c c-func docutils literal">drm_property_create()</code></a> with DRM_MODE_PROP_BLOB as the type. Actual blob objects to contain blob data are created using <a class="reference internal" href="#c.drm_property_create_blob" title="drm_property_create_blob"><code class="xref c c-func docutils literal">drm_property_create_blob()</code></a>, or through the corresponding IOCTL. Besides the built-in limit to only accept blob objects blob properties work exactly like object properties. The only reasons blob properties exist is backwards compatibility with existing userspace. </dd> </dl> In addition a property can have any combination of the below flags: <dl class="last docutils"> <dt>DRM_MODE_PROP_ATOMIC</dt> <dd>Set for properties which encode atomic modeset state. Such properties are not exposed to legacy userspace.</dd> <dt>DRM_MODE_PROP_IMMUTABLE</dt> <dd>Set for properties where userspace cannot be changed by userspace. The kernel is allowed to update the value of these properties. This is generally used to expose probe state to usersapce, e.g. the EDID, or the connector path property on DP MST sinks.</dd> </dl> </dd> <dt><code class="docutils literal">name</code></dt> <dd>symbolic name of the properties</dd> <dt><code class="docutils literal">num_values</code></dt> <dd>size of the values array.</dd> <dt><code class="docutils literal">values</code></dt> <dd>Array with limits and values for the property. The interpretation of these limits is dependent upon the type per flags.</dd> <dt><code class="docutils literal">dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">enum_list</code></dt> <dd>List of <code class="xref c c-type docutils literal">drm_prop_enum_list</code> structures with the symbolic names for enum and bitmask values.</dd> </dl> Description This structure represent a modeset object property. It combines both the name of the property with the set of permissible values. This means that when a driver wants to use a property with the same name on different objects, but with different value ranges, then it must create property for each one. An example would be rotation of <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a>, when e.g. the primary plane cannot be rotated. But if both the name and the value range match, then the same property structure can be instantiated multiple times for the same object. Userspace must be able to cope with this and cannot assume that the same symbolic property will have the same modeset object ID on all modeset objects. Properties are created by one of the special functions, as explained in detail in the flags structure member. To actually expose a property it must be attached to each object using <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. Currently properties can only be attached to <a class="reference internal" href="#c.drm_connector" title="drm_connector"><code class="xref c c-type docutils literal">drm_connector</code></a>, <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> and <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a>. Properties are also used as the generic metadatatransport for the atomic IOCTL. Everything that was set directly in structures in the legacy modeset IOCTLs (like the plane source or destination windows, or e.g. the links to the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set. <dl class="type"> <dt id="c.drm_property_blob"> struct <code class="descname">drm_property_blob</code><a class="headerlink" href="#c.drm_property_blob" title="Permalink to this definition">¶</a></dt> <dd>Blob data for <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a> </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_property_blob { struct drm_mode_object base; struct drm_device *dev; struct list_head head_global; struct list_head head_file; size_t length; unsigned char data[]; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">base</code></dt> <dd>base KMS object</dd> <dt><code class="docutils literal">dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">head_global</code></dt> <dd>entry on the global blob list in <a class="reference internal" href="#c.drm_mode_config" title="drm_mode_config"><code class="xref c c-type docutils literal">drm_mode_config.property_blob_list</code></a>.</dd> <dt><code class="docutils literal">head_file</code></dt> <dd>entry on the per-file blob list in <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file"><code class="xref c c-type docutils literal">drm_file.blobs</code></a> list.</dd> <dt><code class="docutils literal">length</code></dt> <dd>size of the blob in bytes, invariant over the lifetime of the object</dd> <dt><code class="docutils literal">data</code></dt> <dd>actual data, embedded at the end of this structure</dd> </dl> Description Blobs are used to store bigger values than what fits directly into the 64 bits available for a <a class="reference internal" href="#c.drm_property" title="drm_property"><code class="xref c c-type docutils literal">drm_property</code></a>. Blobs are reference counted using <a class="reference internal" href="#c.drm_property_blob_get" title="drm_property_blob_get"><code class="xref c c-func docutils literal">drm_property_blob_get()</code></a> and <a class="reference internal" href="#c.drm_property_blob_put" title="drm_property_blob_put"><code class="xref c c-func docutils literal">drm_property_blob_put()</code></a>. They are created using <a class="reference internal" href="#c.drm_property_create_blob" title="drm_property_create_blob"><code class="xref c c-func docutils literal">drm_property_create_blob()</code></a>. <dl class="function"> <dt id="c.drm_property_type_is"> bool <code class="descname">drm_property_type_is</code>(struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, uint32_t type)<a class="headerlink" href="#c.drm_property_type_is" title="Permalink to this definition">¶</a></dt> <dd>check the type of a property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to check</dd> <dt><code class="docutils literal">uint32_t type</code></dt> <dd>property type to compare with</dd> </dl> Description This is a helper function becauase the uapi encoding of property types is a bit special for historical reasons. <dl class="function"> <dt id="c.drm_property_reference_blob"> struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * <code class="descname">drm_property_reference_blob</code>(struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * blob)<a class="headerlink" href="#c.drm_property_reference_blob" title="Permalink to this definition">¶</a></dt> <dd>acquire a blob property reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property_blob * blob</code></dt> <dd>DRM blob property</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_property_blob_get" title="drm_property_blob_get"><code class="xref c c-func docutils literal">drm_property_blob_get()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_property_unreference_blob"> void <code class="descname">drm_property_unreference_blob</code>(struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * blob)<a class="headerlink" href="#c.drm_property_unreference_blob" title="Permalink to this definition">¶</a></dt> <dd>release a blob property reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property_blob * blob</code></dt> <dd>DRM blob property</dd> </dl> Description This is a compatibility alias for <a class="reference internal" href="#c.drm_property_blob_put" title="drm_property_blob_put"><code class="xref c c-func docutils literal">drm_property_blob_put()</code></a> and should not be used by new code. <dl class="function"> <dt id="c.drm_property_find"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_find</code>(struct drm_device * dev, struct <a class="reference internal" href="drm-internals.html#c.drm_file" title="drm_file">drm_file</a> * file_priv, uint32_t id)<a class="headerlink" href="#c.drm_property_find" title="Permalink to this definition">¶</a></dt> <dd>find property object </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_file * file_priv</code></dt> <dd>drm file to check for lease against.</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>property object id</dd> </dl> Description This function looks up the property object specified by id and returns it. <dl class="function"> <dt id="c.drm_property_create"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create</code>(struct drm_device * dev, int flags, const char * name, int num_values)<a class="headerlink" href="#c.drm_property_create" title="Permalink to this definition">¶</a></dt> <dd>create a new property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">int num_values</code></dt> <dd>number of pre-defined values</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_enum"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_enum</code>(struct drm_device * dev, int flags, const char * name, const struct drm_prop_enum_list * props, int num_values)<a class="headerlink" href="#c.drm_property_create_enum" title="Permalink to this definition">¶</a></dt> <dd>create a new enumeration property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">const struct drm_prop_enum_list * props</code></dt> <dd>enumeration lists with property values</dd> <dt><code class="docutils literal">int num_values</code></dt> <dd>number of pre-defined values</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Userspace is only allowed to set one of the predefined values for enumeration properties. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_bitmask"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_bitmask</code>(struct drm_device * dev, int flags, const char * name, const struct drm_prop_enum_list * props, int num_props, uint64_t supported_bits)<a class="headerlink" href="#c.drm_property_create_bitmask" title="Permalink to this definition">¶</a></dt> <dd>create a new bitmask property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">const struct drm_prop_enum_list * props</code></dt> <dd>enumeration lists with property bitflags</dd> <dt><code class="docutils literal">int num_props</code></dt> <dd>size of the props array</dd> <dt><code class="docutils literal">uint64_t supported_bits</code></dt> <dd>bitmask of all supported enumeration values</dd> </dl> Description This creates a new bitmask drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Compared to plain enumeration properties userspace is allowed to set any or’ed together combination of the predefined property bitflag values Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_range"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_range</code>(struct drm_device * dev, int flags, const char * name, uint64_t min, uint64_t max)<a class="headerlink" href="#c.drm_property_create_range" title="Permalink to this definition">¶</a></dt> <dd>create a new unsigned ranged property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">uint64_t min</code></dt> <dd>minimum value of the property</dd> <dt><code class="docutils literal">uint64_t max</code></dt> <dd>maximum value of the property</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Userspace is allowed to set any unsigned integer value in the (min, max) range inclusive. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_signed_range"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_signed_range</code>(struct drm_device * dev, int flags, const char * name, int64_t min, int64_t max)<a class="headerlink" href="#c.drm_property_create_signed_range" title="Permalink to this definition">¶</a></dt> <dd>create a new signed ranged property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">int64_t min</code></dt> <dd>minimum value of the property</dd> <dt><code class="docutils literal">int64_t max</code></dt> <dd>maximum value of the property</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Userspace is allowed to set any signed integer value in the (min, max) range inclusive. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_object"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_object</code>(struct drm_device * dev, int flags, const char * name, uint32_t type)<a class="headerlink" href="#c.drm_property_create_object" title="Permalink to this definition">¶</a></dt> <dd>create a new object property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> <dt><code class="docutils literal">uint32_t type</code></dt> <dd>object type from DRM_MODE_OBJECT_* defines</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. Userspace is only allowed to set this to any property value of the given type. Only useful for atomic properties, which is enforced. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_create_bool"> struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * <code class="descname">drm_property_create_bool</code>(struct drm_device * dev, int flags, const char * name)<a class="headerlink" href="#c.drm_property_create_bool" title="Permalink to this definition">¶</a></dt> <dd>create a new boolean property type </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">int flags</code></dt> <dd>flags specifying the property type</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>name of the property</dd> </dl> Description This creates a new generic drm property which can then be attached to a drm object with <a class="reference internal" href="#c.drm_object_attach_property" title="drm_object_attach_property"><code class="xref c c-func docutils literal">drm_object_attach_property()</code></a>. The returned property object must be freed with <a class="reference internal" href="#c.drm_property_destroy" title="drm_property_destroy"><code class="xref c c-func docutils literal">drm_property_destroy()</code></a>, which is done automatically when calling <a class="reference internal" href="#c.drm_mode_config_cleanup" title="drm_mode_config_cleanup"><code class="xref c c-func docutils literal">drm_mode_config_cleanup()</code></a>. This is implemented as a ranged property with only {0, 1} as valid values. Return A pointer to the newly created property on success, NULL on failure. <dl class="function"> <dt id="c.drm_property_add_enum"> int <code class="descname">drm_property_add_enum</code>(struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property, int index, uint64_t value, const char * name)<a class="headerlink" href="#c.drm_property_add_enum" title="Permalink to this definition">¶</a></dt> <dd>add a possible value to an enumeration property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>enumeration property to change</dd> <dt><code class="docutils literal">int index</code></dt> <dd>index of the new enumeration</dd> <dt><code class="docutils literal">uint64_t value</code></dt> <dd>value of the new enumeration</dd> <dt><code class="docutils literal">const char * name</code></dt> <dd>symbolic name of the new enumeration</dd> </dl> Description This functions adds enumerations to a property. It’s use is deprecated, drivers should use one of the more specific helpers to directly create the property with all enumerations already attached. Return Zero on success, error code on failure. <dl class="function"> <dt id="c.drm_property_destroy"> void <code class="descname">drm_property_destroy</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * property)<a class="headerlink" href="#c.drm_property_destroy" title="Permalink to this definition">¶</a></dt> <dd>destroy a drm property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">struct drm_property * property</code></dt> <dd>property to destry</dd> </dl> Description This function frees a property including any attached resources like enumeration values. <dl class="function"> <dt id="c.drm_property_create_blob"> struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * <code class="descname">drm_property_create_blob</code>(struct drm_device * dev, size_t length, const void * data)<a class="headerlink" href="#c.drm_property_create_blob" title="Permalink to this definition">¶</a></dt> <dd>Create new blob property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device to create property for</dd> <dt><code class="docutils literal">size_t length</code></dt> <dd>Length to allocate for blob data</dd> <dt><code class="docutils literal">const void * data</code></dt> <dd>If specified, copies data into blob</dd> </dl> Description Creates a new blob property for a specified DRM device, optionally copying data. Note that blob properties are meant to be invariant, hence the data must be filled out before the blob is used as the value of any property. Return New blob property with a single reference on success, or an ERR_PTR value on failure. <dl class="function"> <dt id="c.drm_property_blob_put"> void <code class="descname">drm_property_blob_put</code>(struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * blob)<a class="headerlink" href="#c.drm_property_blob_put" title="Permalink to this definition">¶</a></dt> <dd>release a blob property reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property_blob * blob</code></dt> <dd>DRM blob property</dd> </dl> Description Releases a reference to a blob property. May free the object. <dl class="function"> <dt id="c.drm_property_blob_get"> struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * <code class="descname">drm_property_blob_get</code>(struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * blob)<a class="headerlink" href="#c.drm_property_blob_get" title="Permalink to this definition">¶</a></dt> <dd>acquire blob property reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property_blob * blob</code></dt> <dd>DRM blob property</dd> </dl> Description Acquires a reference to an existing blob property. Returns blob, which allows this to be used as a shorthand in assignments. <dl class="function"> <dt id="c.drm_property_lookup_blob"> struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * <code class="descname">drm_property_lookup_blob</code>(struct drm_device * dev, uint32_t id)<a class="headerlink" href="#c.drm_property_lookup_blob" title="Permalink to this definition">¶</a></dt> <dd>look up a blob property and take a reference </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">uint32_t id</code></dt> <dd>id of the blob property</dd> </dl> Description If successful, this takes an additional reference to the blob property. callers need to make sure to eventually unreference the returned property again, using <a class="reference internal" href="#c.drm_property_blob_put" title="drm_property_blob_put"><code class="xref c c-func docutils literal">drm_property_blob_put()</code></a>. Return NULL on failure, pointer to the blob on success. <dl class="function"> <dt id="c.drm_property_replace_global_blob"> int <code class="descname">drm_property_replace_global_blob</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> ** replace, size_t length, const void * data, struct <a class="reference internal" href="#c.drm_mode_object" title="drm_mode_object">drm_mode_object</a> * obj_holds_id, struct <a class="reference internal" href="#c.drm_property" title="drm_property">drm_property</a> * prop_holds_id)<a class="headerlink" href="#c.drm_property_replace_global_blob" title="Permalink to this definition">¶</a></dt> <dd>replace existing blob property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>drm device</dd> <dt><code class="docutils literal">struct drm_property_blob ** replace</code></dt> <dd>location of blob property pointer to be replaced</dd> <dt><code class="docutils literal">size_t length</code></dt> <dd>length of data for new blob, or 0 for no data</dd> <dt><code class="docutils literal">const void * data</code></dt> <dd>content for new blob, or NULL for no data</dd> <dt><code class="docutils literal">struct drm_mode_object * obj_holds_id</code></dt> <dd>optional object for property holding blob ID</dd> <dt><code class="docutils literal">struct drm_property * prop_holds_id</code></dt> <dd>optional property holding blob ID return 0 on success or error on failure</dd> </dl> Description This function will replace a global property in the blob list, optionally updating a property which holds the ID of that property. If length is 0 or data is NULL, no new blob will be created, and the holding property, if specified, will be set to 0. Access to the replace pointer is assumed to be protected by the caller, e.g. by holding the relevant modesetting object lock for its parent. For example, a drm_connector has a ‘PATH’ property, which contains the ID of a blob property with the value of the MST path information. Calling this function with replace pointing to the connector’s path_blob_ptr, length and data set for the new path information, obj_holds_id set to the connector’s base object, and prop_holds_id set to the path property name, will perform a completely atomic update. The access to path_blob_ptr is protected by the caller holding a lock on the connector. <dl class="function"> <dt id="c.drm_property_replace_blob"> bool <code class="descname">drm_property_replace_blob</code>(struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> ** blob, struct <a class="reference internal" href="#c.drm_property_blob" title="drm_property_blob">drm_property_blob</a> * new_blob)<a class="headerlink" href="#c.drm_property_replace_blob" title="Permalink to this definition">¶</a></dt> <dd>replace a blob property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_property_blob ** blob</code></dt> <dd>a pointer to the member blob to be replaced</dd> <dt><code class="docutils literal">struct drm_property_blob * new_blob</code></dt> <dd>the new blob to replace with</dd> </dl> Return true if the blob was in fact replaced. </div> <div class="section" id="standard-connector-properties"> <h3>Standard Connector Properties<a class="headerlink" href="#standard-connector-properties" title="Permalink to this headline">¶</a></h3> DRM connectors have a few standardized properties: <dl class="docutils"> <dt>EDID:</dt> <dd>Blob property which contains the current EDID read from the sink. This is useful to parse sink identification information like vendor, model and serial. Drivers should update this property by calling <a class="reference internal" href="#c.drm_mode_connector_update_edid_property" title="drm_mode_connector_update_edid_property"><code class="xref c c-func docutils literal">drm_mode_connector_update_edid_property()</code></a>, usually after having parsed the EDID using <a class="reference internal" href="drm-kms-helpers.html#c.drm_add_edid_modes" title="drm_add_edid_modes"><code class="xref c c-func docutils literal">drm_add_edid_modes()</code></a>. Userspace cannot change this property.</dd> <dt>DPMS:</dt> <dd>Legacy property for setting the power state of the connector. For atomic drivers this is only provided for backwards compatibility with existing drivers, it remaps to controlling the “ACTIVE” property on the CRTC the connector is linked to. Drivers should never set this property directly, it is handled by the DRM core by calling the <a class="reference internal" href="#c.drm_connector_funcs" title="drm_connector_funcs"><code class="xref c c-type docutils literal">drm_connector_funcs.dpms</code></a> callback. For atomic drivers the remapping to the “ACTIVE” property is implemented in the DRM core. This is the only standard connector property that userspace can change. Note that this property cannot be set through the MODE_ATOMIC ioctl, userspace must use “ACTIVE” on the CRTC instead. WARNING: For userspace also running on legacy drivers the “DPMS” semantics are a lot more complicated. First, userspace cannot rely on the “DPMS” value returned by the GETCONNECTOR actually reflecting reality, because many drivers fail to update it. For atomic drivers this is taken care of in <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_update_legacy_modeset_state" title="drm_atomic_helper_update_legacy_modeset_state"><code class="xref c c-func docutils literal">drm_atomic_helper_update_legacy_modeset_state()</code></a>. The second issue is that the DPMS state is only well-defined when the connector is connected to a CRTC. In atomic the DRM core enforces that “ACTIVE” is off in such a case, no such checks exists for “DPMS”. Finally, when enabling an output using the legacy SETCONFIG ioctl then “DPMS” is forced to ON. But see above, that might not be reflected in the software value on legacy drivers. Summarizing: Only set “DPMS” when the connector is known to be enabled, assume that a successful SETCONFIG call also sets “DPMS” to on, and never read back the value of “DPMS” because it can be incorrect. </dd> <dt>PATH:</dt> <dd>Connector path property to identify how this sink is physically connected. Used by DP MST. This should be set by calling <a class="reference internal" href="#c.drm_mode_connector_set_path_property" title="drm_mode_connector_set_path_property"><code class="xref c c-func docutils literal">drm_mode_connector_set_path_property()</code></a>, in the case of DP MST with the path property the MST manager created. Userspace cannot change this property.</dd> <dt>TILE:</dt> <dd>Connector tile group property to indicate how a set of DRM connector compose together into one logical screen. This is used by both high-res external screens (often only using a single cable, but exposing multiple DP MST sinks), or high-res integrated panels (like dual-link DSI) which are not gen-locked. Note that for tiled panels which are genlocked, like dual-link LVDS or dual-link DSI, the driver should try to not expose the tiling and virtualize both <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> and <a class="reference internal" href="#c.drm_plane" title="drm_plane"><code class="xref c c-type docutils literal">drm_plane</code></a> if needed. Drivers should update this value using <a class="reference internal" href="#c.drm_mode_connector_set_tile_property" title="drm_mode_connector_set_tile_property"><code class="xref c c-func docutils literal">drm_mode_connector_set_tile_property()</code></a>. Userspace cannot change this property.</dd> <dt>link-status:</dt> <dd>Connector link-status property to indicate the status of link. The default value of link-status is “GOOD”. If something fails during or after modeset, the kernel driver may set this to “BAD” and issue a hotplug uevent. Drivers should update this value using <a class="reference internal" href="#c.drm_mode_connector_set_link_status_property" title="drm_mode_connector_set_link_status_property"><code class="xref c c-func docutils literal">drm_mode_connector_set_link_status_property()</code></a>.</dd> <dt>non_desktop:</dt> <dd>Indicates the output should be ignored for purposes of displaying a standard desktop environment or console. This is most likely because the output device is not rectilinear.</dd> </dl> Connectors also have one standardized atomic property: <dl class="docutils"> <dt>CRTC_ID:</dt> <dd>Mode object ID of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> this connector should be connected to.</dd> </dl> Connectors for LCD panels may also have one standardized property: <dl class="docutils"> <dt>panel orientation:</dt> <dd>On some devices the LCD panel is mounted in the casing in such a way that the up/top side of the panel does not match with the top side of the device. Userspace can use this property to check for this. Note that input coordinates from touchscreens (input devices with INPUT_PROP_DIRECT) will still map 1:1 to the actual LCD panel coordinates, so if userspace rotates the picture to adjust for the orientation it must also apply the same transformation to the touchscreen input coordinates.</dd> </dl> </div> <div class="section" id="plane-composition-properties"> <h3>Plane Composition Properties<a class="headerlink" href="#plane-composition-properties" title="Permalink to this headline">¶</a></h3> The basic plane composition model supported by standard plane properties only has a source rectangle (in logical pixels within the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>), with sub-pixel accuracy, which is scaled up to a pixel-aligned destination rectangle in the visible area of a <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>. The visible area of a CRTC is defined by the horizontal and vertical visible pixels (stored in hdisplay and vdisplay) of the requested mode (stored in <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.mode</code></a>). These two rectangles are both stored in the <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state</code></a>. For the atomic ioctl the following standard (atomic) properties on the plane object encode the basic plane composition model: <dl class="docutils"> <dt>SRC_X:</dt> <dd>X coordinate offset for the source rectangle within the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>, in 16.16 fixed point. Must be positive.</dd> <dt>SRC_Y:</dt> <dd>Y coordinate offset for the source rectangle within the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>, in 16.16 fixed point. Must be positive.</dd> <dt>SRC_W:</dt> <dd>Width for the source rectangle within the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>, in 16.16 fixed point. SRC_X plus SRC_W must be within the width of the source framebuffer. Must be positive.</dd> <dt>SRC_H:</dt> <dd>Height for the source rectangle within the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>, in 16.16 fixed point. SRC_Y plus SRC_H must be within the height of the source framebuffer. Must be positive.</dd> <dt>CRTC_X:</dt> <dd>X coordinate offset for the destination rectangle. Can be negative.</dd> <dt>CRTC_Y:</dt> <dd>Y coordinate offset for the destination rectangle. Can be negative.</dd> <dt>CRTC_W:</dt> <dd>Width for the destination rectangle. CRTC_X plus CRTC_W can extend past the currently visible horizontal area of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>.</dd> <dt>CRTC_H:</dt> <dd>Height for the destination rectangle. CRTC_Y plus CRTC_H can extend past the currently visible vertical area of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a>.</dd> <dt>FB_ID:</dt> <dd>Mode object ID of the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a> this plane should scan out.</dd> <dt>CRTC_ID:</dt> <dd>Mode object ID of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> this plane should be connected to.</dd> </dl> Note that the source rectangle must fully lie within the bounds of the <a class="reference internal" href="#c.drm_framebuffer" title="drm_framebuffer"><code class="xref c c-type docutils literal">drm_framebuffer</code></a>. The destination rectangle can lie outside of the visible area of the current mode of the CRTC. It must be apprpriately clipped by the driver, which can be done by calling <a class="reference internal" href="drm-kms-helpers.html#c.drm_plane_helper_check_update" title="drm_plane_helper_check_update"><code class="xref c c-func docutils literal">drm_plane_helper_check_update()</code></a>. Drivers are also allowed to round the subpixel sampling positions appropriately, but only to the next full pixel. No pixel outside of the source rectangle may ever be sampled, which is important when applying more sophisticated filtering than just a bilinear one when scaling. The filtering mode when scaling is unspecified. On top of this basic transformation additional properties can be exposed by the driver: <ul class="simple"> <li>Rotation is set up with <a class="reference internal" href="#c.drm_plane_create_rotation_property" title="drm_plane_create_rotation_property"><code class="xref c c-func docutils literal">drm_plane_create_rotation_property()</code></a>. It adds a rotation and reflection step between the source and destination rectangles. Without this property the rectangle is only scaled, but not rotated or reflected.</li> <li>Z position is set up with <a class="reference internal" href="#c.drm_plane_create_zpos_immutable_property" title="drm_plane_create_zpos_immutable_property"><code class="xref c c-func docutils literal">drm_plane_create_zpos_immutable_property()</code></a> and <a class="reference internal" href="#c.drm_plane_create_zpos_property" title="drm_plane_create_zpos_property"><code class="xref c c-func docutils literal">drm_plane_create_zpos_property()</code></a>. It controls the visibility of overlapping planes. Without this property the primary plane is always below the cursor plane, and ordering between all other planes is undefined.</li> </ul> Note that all the property extensions described here apply either to the plane or the CRTC (e.g. for the background color, which currently is not exposed and assumed to be black). <dl class="function"> <dt id="c.drm_plane_create_rotation_property"> int <code class="descname">drm_plane_create_rotation_property</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, unsigned int rotation, unsigned int supported_rotations)<a class="headerlink" href="#c.drm_plane_create_rotation_property" title="Permalink to this definition">¶</a></dt> <dd>create a new rotation property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>drm plane</dd> <dt><code class="docutils literal">unsigned int rotation</code></dt> <dd>initial value of the rotation property</dd> <dt><code class="docutils literal">unsigned int supported_rotations</code></dt> <dd>bitmask of supported rotations and reflections</dd> </dl> Description This creates a new property with the selected support for transformations. Since a rotation by 180° degress is the same as reflecting both along the x and the y axis the rotation property is somewhat redundant. Drivers can use <a class="reference internal" href="#c.drm_rotation_simplify" title="drm_rotation_simplify"><code class="xref c c-func docutils literal">drm_rotation_simplify()</code></a> to normalize values of this property. The property exposed to userspace is a bitmask property (see <a class="reference internal" href="#c.drm_property_create_bitmask" title="drm_property_create_bitmask"><code class="xref c c-func docutils literal">drm_property_create_bitmask()</code></a>) called “rotation” and has the following bitmask enumaration values: <dl class="docutils"> <dt>DRM_MODE_ROTATE_0:</dt> <dd>“rotate-0”</dd> <dt>DRM_MODE_ROTATE_90:</dt> <dd>“rotate-90”</dd> <dt>DRM_MODE_ROTATE_180:</dt> <dd>“rotate-180”</dd> <dt>DRM_MODE_ROTATE_270:</dt> <dd>“rotate-270”</dd> <dt>DRM_MODE_REFLECT_X:</dt> <dd>“reflect-x”</dd> <dt>DRM_MODE_REFLECT_Y:</dt> <dd>“reflect-y”</dd> </dl> Rotation is the specified amount in degrees in counter clockwise direction, the X and Y axis are within the source rectangle, i.e. the X/Y axis before rotation. After reflection, the rotation is applied to the image sampled from the source rectangle, before scaling it to fit the destination rectangle. <dl class="function"> <dt id="c.drm_rotation_simplify"> unsigned int <code class="descname">drm_rotation_simplify</code>(unsigned int rotation, unsigned int supported_rotations)<a class="headerlink" href="#c.drm_rotation_simplify" title="Permalink to this definition">¶</a></dt> <dd>Try to simplify the rotation </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">unsigned int rotation</code></dt> <dd>Rotation to be simplified</dd> <dt><code class="docutils literal">unsigned int supported_rotations</code></dt> <dd>Supported rotations</dd> </dl> Description Attempt to simplify the rotation to a form that is supported. Eg. if the hardware supports everything except DRM_MODE_REFLECT_X one could call this function like this: <dl class="docutils"> <dt>drm_rotation_simplify(rotation, DRM_MODE_ROTATE_0 |</dt> <dd>DRM_MODE_ROTATE_90 | DRM_MODE_ROTATE_180 | DRM_MODE_ROTATE_270 | DRM_MODE_REFLECT_Y);</dd> </dl> to eliminate the DRM_MODE_ROTATE_X flag. Depending on what kind of transforms the hardware supports, this function may not be able to produce a supported transform, so the caller should check the result afterwards. <dl class="function"> <dt id="c.drm_plane_create_zpos_property"> int <code class="descname">drm_plane_create_zpos_property</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, unsigned int zpos, unsigned int min, unsigned int max)<a class="headerlink" href="#c.drm_plane_create_zpos_property" title="Permalink to this definition">¶</a></dt> <dd>create mutable zpos property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>drm plane</dd> <dt><code class="docutils literal">unsigned int zpos</code></dt> <dd>initial value of zpos property</dd> <dt><code class="docutils literal">unsigned int min</code></dt> <dd>minimal possible value of zpos property</dd> <dt><code class="docutils literal">unsigned int max</code></dt> <dd>maximal possible value of zpos property</dd> </dl> Description This function initializes generic mutable zpos property and enables support for it in drm core. Drivers can then attach this property to planes to enable support for configurable planes arrangement during blending operation. Drivers that attach a mutable zpos property to any plane should call the <a class="reference internal" href="#c.drm_atomic_normalize_zpos" title="drm_atomic_normalize_zpos"><code class="xref c c-func docutils literal">drm_atomic_normalize_zpos()</code></a> helper during their implementation of <a class="reference internal" href="#c.drm_mode_config_funcs" title="drm_mode_config_funcs"><code class="xref c c-type docutils literal">drm_mode_config_funcs.atomic_check()</code></a>, which will update the normalized zpos values and store them in <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state.normalized_zpos</code></a>. Usually min should be set to 0 and max to maximal number of planes for given crtc - 1. If zpos of some planes cannot be changed (like fixed background or cursor/topmost planes), driver should adjust min/max values and assign those planes immutable zpos property with lower or higher values (for more information, see <a class="reference internal" href="#c.drm_plane_create_zpos_immutable_property" title="drm_plane_create_zpos_immutable_property"><code class="xref c c-func docutils literal">drm_plane_create_zpos_immutable_property()</code></a> function). In such case driver should also assign proper initial zpos values for all planes in its <code class="xref c c-func docutils literal">plane_reset()</code> callback, so the planes will be always sorted properly. See also <a class="reference internal" href="#c.drm_atomic_normalize_zpos" title="drm_atomic_normalize_zpos"><code class="xref c c-func docutils literal">drm_atomic_normalize_zpos()</code></a>. The property exposed to userspace is called “zpos”. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_plane_create_zpos_immutable_property"> int <code class="descname">drm_plane_create_zpos_immutable_property</code>(struct <a class="reference internal" href="#c.drm_plane" title="drm_plane">drm_plane</a> * plane, unsigned int zpos)<a class="headerlink" href="#c.drm_plane_create_zpos_immutable_property" title="Permalink to this definition">¶</a></dt> <dd>create immuttable zpos property </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_plane * plane</code></dt> <dd>drm plane</dd> <dt><code class="docutils literal">unsigned int zpos</code></dt> <dd>value of zpos property</dd> </dl> Description This function initializes generic immutable zpos property and enables support for it in drm core. Using this property driver lets userspace to get the arrangement of the planes for blending operation and notifies it that the hardware (or driver) doesn’t support changing of the planes’ order. For mutable zpos see <a class="reference internal" href="#c.drm_plane_create_zpos_property" title="drm_plane_create_zpos_property"><code class="xref c c-func docutils literal">drm_plane_create_zpos_property()</code></a>. The property exposed to userspace is called “zpos”. Return Zero on success, negative errno on failure. <dl class="function"> <dt id="c.drm_atomic_normalize_zpos"> int <code class="descname">drm_atomic_normalize_zpos</code>(struct drm_device * dev, struct <a class="reference internal" href="#c.drm_atomic_state" title="drm_atomic_state">drm_atomic_state</a> * state)<a class="headerlink" href="#c.drm_atomic_normalize_zpos" title="Permalink to this definition">¶</a></dt> <dd>calculate normalized zpos values for all crtcs </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">struct drm_atomic_state * state</code></dt> <dd>atomic state of DRM device</dd> </dl> Description This function calculates normalized zpos value for all modified planes in the provided atomic state of DRM device. For every CRTC this function checks new states of all planes assigned to it and calculates normalized zpos value for these planes. Planes are compared first by their zpos values, then by plane id (if zpos is equal). The plane with lowest zpos value is at the bottom. The <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">drm_plane_state.normalized_zpos</code></a> is then filled with unique values from 0 to number of active planes in crtc minus one. RETURNS Zero for success or -errno </div> <div class="section" id="color-management-properties"> <h3>Color Management Properties<a class="headerlink" href="#color-management-properties" title="Permalink to this headline">¶</a></h3> Color management or color space adjustments is supported through a set of 5 properties on the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> object. They are set up by calling <a class="reference internal" href="#c.drm_crtc_enable_color_mgmt" title="drm_crtc_enable_color_mgmt"><code class="xref c c-func docutils literal">drm_crtc_enable_color_mgmt()</code></a>. <dl class="docutils"> <dt>“DEGAMMA_LUT”:</dt> <dd>Blob property to set the degamma lookup table (LUT) mapping pixel data from the framebuffer before it is given to the transformation matrix. The data is interpreted as an array of <code class="xref c c-type docutils literal">struct drm_color_lut</code> elements. Hardware might choose not to use the full precision of the LUT elements nor use all the elements of the LUT (for example the hardware might choose to interpolate between LUT[0] and LUT[4]). Setting this to NULL (blob property value set to 0) means a linear/pass-thru gamma table should be used. This is generally the driver boot-up state too. Drivers can access this blob through <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.degamma_lut</code></a>. </dd> <dt>“DEGAMMA_LUT_SIZE”:</dt> <dd>Unsinged range property to give the size of the lookup table to be set on the DEGAMMA_LUT property (the size depends on the underlying hardware). If drivers support multiple LUT sizes then they should publish the largest size, and sub-sample smaller sized LUTs (e.g. for split-gamma modes) appropriately.</dd> <dt>“CTM”:</dt> <dd>Blob property to set the current transformation matrix (CTM) apply to pixel data after the lookup through the degamma LUT and before the lookup through the gamma LUT. The data is interpreted as a struct <code class="xref c c-type docutils literal">drm_color_ctm</code>. Setting this to NULL (blob property value set to 0) means a unit/pass-thru matrix should be used. This is generally the driver boot-up state too. Drivers can access the blob for the color conversion matrix through <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.ctm</code></a>. </dd> <dt>“GAMMA_LUT”:</dt> <dd>Blob property to set the gamma lookup table (LUT) mapping pixel data after the transformation matrix to data sent to the connector. The data is interpreted as an array of <code class="xref c c-type docutils literal">struct drm_color_lut</code> elements. Hardware might choose not to use the full precision of the LUT elements nor use all the elements of the LUT (for example the hardware might choose to interpolate between LUT[0] and LUT[4]). Setting this to NULL (blob property value set to 0) means a linear/pass-thru gamma table should be used. This is generally the driver boot-up state too. Drivers can access this blob through <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.gamma_lut</code></a>. </dd> <dt>“GAMMA_LUT_SIZE”:</dt> <dd>Unsigned range property to give the size of the lookup table to be set on the GAMMA_LUT property (the size depends on the underlying hardware). If drivers support multiple LUT sizes then they should publish the largest size, and sub-sample smaller sized LUTs (e.g. for split-gamma modes) appropriately.</dd> </dl> There is also support for a legacy gamma table, which is set up by calling <a class="reference internal" href="#c.drm_mode_crtc_set_gamma_size" title="drm_mode_crtc_set_gamma_size"><code class="xref c c-func docutils literal">drm_mode_crtc_set_gamma_size()</code></a>. Drivers which support both should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_legacy_gamma_set" title="drm_atomic_helper_legacy_gamma_set"><code class="xref c c-func docutils literal">drm_atomic_helper_legacy_gamma_set()</code></a> to alias the legacy gamma ramp with the “GAMMA_LUT” property above. <dl class="function"> <dt id="c.drm_color_lut_extract"> uint32_t <code class="descname">drm_color_lut_extract</code>(uint32_t user_input, uint32_t bit_precision)<a class="headerlink" href="#c.drm_color_lut_extract" title="Permalink to this definition">¶</a></dt> <dd>clamp and round LUT entries </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">uint32_t user_input</code></dt> <dd>input value</dd> <dt><code class="docutils literal">uint32_t bit_precision</code></dt> <dd>number of bits the hw LUT supports</dd> </dl> Description Extract a degamma/gamma LUT value provided by user (in the form of <code class="xref c c-type docutils literal">drm_color_lut</code> entries) and round it to the precision supported by the hardware. <dl class="function"> <dt id="c.drm_crtc_enable_color_mgmt"> void <code class="descname">drm_crtc_enable_color_mgmt</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, uint degamma_lut_size, bool has_ctm, uint gamma_lut_size)<a class="headerlink" href="#c.drm_crtc_enable_color_mgmt" title="Permalink to this definition">¶</a></dt> <dd>enable color management properties </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>DRM CRTC</dd> <dt><code class="docutils literal">uint degamma_lut_size</code></dt> <dd>the size of the degamma lut (before CSC)</dd> <dt><code class="docutils literal">bool has_ctm</code></dt> <dd>whether to attach ctm_property for CSC matrix</dd> <dt><code class="docutils literal">uint gamma_lut_size</code></dt> <dd>the size of the gamma lut (after CSC)</dd> </dl> Description This function lets the driver enable the color correction properties on a CRTC. This includes 3 degamma, csc and gamma properties that userspace can set and 2 size properties to inform the userspace of the lut sizes. Each of the properties are optional. The gamma and degamma properties are only attached if their size is not 0 and ctm_property is only attached if has_ctm is true. Drivers should use <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_legacy_gamma_set" title="drm_atomic_helper_legacy_gamma_set"><code class="xref c c-func docutils literal">drm_atomic_helper_legacy_gamma_set()</code></a> to implement the legacy <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.gamma_set</code></a> callback. <dl class="function"> <dt id="c.drm_mode_crtc_set_gamma_size"> int <code class="descname">drm_mode_crtc_set_gamma_size</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, int gamma_size)<a class="headerlink" href="#c.drm_mode_crtc_set_gamma_size" title="Permalink to this definition">¶</a></dt> <dd>set the gamma table size </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC to set the gamma table size for</dd> <dt><code class="docutils literal">int gamma_size</code></dt> <dd>size of the gamma table</dd> </dl> Description Drivers which support gamma tables should set this to the supported gamma table size when initializing the CRTC. Currently the drm core only supports a fixed gamma table size. Return Zero on success, negative errno on failure. </div> <div class="section" id="tile-group-property"> <h3>Tile Group Property<a class="headerlink" href="#tile-group-property" title="Permalink to this headline">¶</a></h3> Tile groups are used to represent tiled monitors with a unique integer identifier. Tiled monitors using DisplayID v1.3 have a unique 8-byte handle, we store this in a tile group, so we have a common identifier for all tiles in a monitor group. The property is called “TILE”. Drivers can manage tile groups using <a class="reference internal" href="#c.drm_mode_create_tile_group" title="drm_mode_create_tile_group"><code class="xref c c-func docutils literal">drm_mode_create_tile_group()</code></a>, <a class="reference internal" href="#c.drm_mode_put_tile_group" title="drm_mode_put_tile_group"><code class="xref c c-func docutils literal">drm_mode_put_tile_group()</code></a> and <a class="reference internal" href="#c.drm_mode_get_tile_group" title="drm_mode_get_tile_group"><code class="xref c c-func docutils literal">drm_mode_get_tile_group()</code></a>. But this is only needed for internal panels where the tile group information is exposed through a non-standard way. </div> <div class="section" id="explicit-fencing-properties"> <h3>Explicit Fencing Properties<a class="headerlink" href="#explicit-fencing-properties" title="Permalink to this headline">¶</a></h3> Explicit fencing allows userspace to control the buffer synchronization between devices. A Fence or a group of fences are transfered to/from userspace using Sync File fds and there are two DRM properties for that. IN_FENCE_FD on each DRM Plane to send fences to the kernel and OUT_FENCE_PTR on each DRM CRTC to receive fences from the kernel. As a contrast, with implicit fencing the kernel keeps track of any ongoing rendering, and automatically ensures that the atomic update waits for any pending rendering to complete. For shared buffers represented with a <a class="reference internal" href="../driver-api/dma-buf.html#c.dma_buf" title="dma_buf"><code class="xref c c-type docutils literal">struct dma_buf</code></a> this is tracked in <a class="reference internal" href="../driver-api/dma-buf.html#c.reservation_object" title="reservation_object"><code class="xref c c-type docutils literal">struct reservation_object</code></a>. Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org), whereas explicit fencing is what Android wants. <dl class="docutils"> <dt>“IN_FENCE_FD”:</dt> <dd>Use this property to pass a fence that DRM should wait on before proceeding with the Atomic Commit request and show the framebuffer for the plane on the screen. The fence can be either a normal fence or a merged one, the sync_file framework will handle both cases and use a fence_array if a merged fence is received. Passing -1 here means no fences to wait on. If the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flag it will only check if the Sync File is a valid one. On the driver side the fence is stored on the fence parameter of <a class="reference internal" href="#c.drm_plane_state" title="drm_plane_state"><code class="xref c c-type docutils literal">struct drm_plane_state</code></a>. Drivers which also support implicit fencing should set the implicit fence using <a class="reference internal" href="#c.drm_atomic_set_fence_for_plane" title="drm_atomic_set_fence_for_plane"><code class="xref c c-func docutils literal">drm_atomic_set_fence_for_plane()</code></a>, to make sure there’s consistent behaviour between drivers in precedence of implicit vs. explicit fencing. </dd> <dt>“OUT_FENCE_PTR”:</dt> <dd>Use this property to pass a file descriptor pointer to DRM. Once the Atomic Commit request call returns OUT_FENCE_PTR will be filled with the file descriptor number of a Sync File. This Sync File contains the CRTC fence that will be signaled when all framebuffers present on the Atomic Commit * request for that given CRTC are scanned out on the screen. The Atomic Commit request fails if a invalid pointer is passed. If the Atomic Commit request fails for any other reason the out fence fd returned will be -1. On a Atomic Commit with the DRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1. Note that out-fences don’t have a special interface to drivers and are internally represented by a <a class="reference internal" href="#c.drm_pending_vblank_event" title="drm_pending_vblank_event"><code class="xref c c-type docutils literal">struct drm_pending_vblank_event</code></a> in struct <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state</code></a>, which is also used by the nonblocking atomic commit helpers and for the DRM event handling for existing userspace. </dd> </dl> </div> <div class="section" id="existing-kms-properties"> <h3>Existing KMS Properties<a class="headerlink" href="#existing-kms-properties" title="Permalink to this headline">¶</a></h3> The following table gives description of drm properties exposed by various modules/drivers. <table border="1" class="docutils"> <colgroup> <col width="14%" /> <col width="14%" /> <col width="14%" /> <col width="14%" /> <col width="14%" /> <col width="14%" /> <col width="14%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Owner Module/Drivers</th> <th class="head">Group</th> <th class="head">Property Name</th> <th class="head">Type</th> <th class="head">Property Values</th> <th class="head">Object attached</th> <th class="head">Description/Restrictions</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td> </td> <td> </td> <td>“scaling mode”</td> <td>ENUM</td> <td>{ “None”, “Full”, “Center”, “Full aspect” }</td> <td>Connector</td> <td>Supported by: amdgpu, gma500, i915, nouveau and radeon.</td> </tr> <tr class="row-odd"><td> </td> <td>DVI-I</td> <td>“subconnector”</td> <td>ENUM</td> <td>{ “Unknown”, “DVI-D”, “DVI-A” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“select subconnector”</td> <td>ENUM</td> <td>{ “Automatic”, “DVI-D”, “DVI-A” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>TV</td> <td>“subconnector”</td> <td>ENUM</td> <td>{ “Unknown”, “Composite”, “SVIDEO”, “Component”, “SCART” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“select subconnector”</td> <td>ENUM</td> <td>{ “Automatic”, “Composite”, “SVIDEO”, “Component”, “SCART” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“mode”</td> <td>ENUM</td> <td>{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“left margin”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“right margin”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“top margin”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“bottom margin”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“contrast”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“flicker reduction”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“overscan”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“saturation”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“hue”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>Virtual GPU</td> <td>“suggested X”</td> <td>RANGE</td> <td>Min=0, Max=0xffffffff</td> <td>Connector</td> <td>property to suggest an X offset for a connector</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“suggested Y”</td> <td>RANGE</td> <td>Min=0, Max=0xffffffff</td> <td>Connector</td> <td>property to suggest an Y offset for a connector</td> </tr> <tr class="row-even"><td> </td> <td>Optional</td> <td>“aspect ratio”</td> <td>ENUM</td> <td>{ “None”, “4:3”, “16:9” }</td> <td>Connector</td> <td>TDB</td> </tr> <tr class="row-odd"><td>i915</td> <td>Generic</td> <td>“Broadcast RGB”</td> <td>ENUM</td> <td>{ “Automatic”, “Full”, “Limited 16:235” }</td> <td>Connector</td> <td>When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255.</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“audio”</td> <td>ENUM</td> <td>{ “force-dvi”, “off”, “auto”, “on” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>SDVO-TV</td> <td>“mode”</td> <td>ENUM</td> <td>{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“left_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“right_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“top_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“bottom_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“hpos”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“vpos”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“contrast”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“saturation”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“hue”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“sharpness”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“flicker_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“flicker_filter_adaptive”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“flicker_filter_2d”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“tv_chroma_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“tv_luma_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“dot_crawl”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>SDVO-TV/LVDS</td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td>CDV gma-500</td> <td>Generic</td> <td>“Broadcast RGB”</td> <td>ENUM</td> <td>{ “Full”, “Limited 16:235” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“Broadcast RGB”</td> <td>ENUM</td> <td>{ “off”, “auto”, “on” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td>Poulsbo</td> <td>Generic</td> <td>“backlight”</td> <td>RANGE</td> <td>Min=0, Max=100</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>SDVO-TV</td> <td>“mode”</td> <td>ENUM</td> <td>{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“left_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“right_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“top_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“bottom_margin”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“hpos”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“vpos”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“contrast”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“saturation”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“hue”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“sharpness”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“flicker_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“flicker_filter_adaptive”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“flicker_filter_2d”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“tv_chroma_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“tv_luma_filter”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“dot_crawl”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>SDVO-TV/LVDS</td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max= SDVO dependent</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td>armada</td> <td>CRTC</td> <td>“CSC_YUV”</td> <td>ENUM</td> <td>{ “Auto” , “CCIR601”, “CCIR709” }</td> <td>CRTC</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“CSC_RGB”</td> <td>ENUM</td> <td>{ “Auto”, “Computer system”, “Studio” }</td> <td>CRTC</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>Overlay</td> <td>“colorkey”</td> <td>RANGE</td> <td>Min=0, Max=0xffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“colorkey_min”</td> <td>RANGE</td> <td>Min=0, Max=0xffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“colorkey_max”</td> <td>RANGE</td> <td>Min=0, Max=0xffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“colorkey_val”</td> <td>RANGE</td> <td>Min=0, Max=0xffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“colorkey_alpha”</td> <td>RANGE</td> <td>Min=0, Max=0xffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“colorkey_mode”</td> <td>ENUM</td> <td>{ “disabled”, “Y component”, “U component” , “V component”, “RGB”, “R component”, “G component”, “B component” }</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max=256 + 255</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“contrast”</td> <td>RANGE</td> <td>Min=0, Max=0x7fff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“saturation”</td> <td>RANGE</td> <td>Min=0, Max=0x7fff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td>exynos</td> <td>CRTC</td> <td>“mode”</td> <td>ENUM</td> <td>{ “normal”, “blank” }</td> <td>CRTC</td> <td>TBD</td> </tr> <tr class="row-even"><td>i2c/ch7006_drv</td> <td>Generic</td> <td>“scale”</td> <td>RANGE</td> <td>Min=0, Max=2</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>TV</td> <td>“mode”</td> <td>ENUM</td> <td>{ “PAL”, “PAL-M”,”PAL-N”}, ”PAL-Nc” , “PAL-60”, “NTSC-M”, “NTSC-J” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td>nouveau</td> <td>NV10 Overlay</td> <td>“colorkey”</td> <td>RANGE</td> <td>Min=0, Max=0x01ffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“contrast”</td> <td>RANGE</td> <td>Min=0, Max=8192-1</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max=1024</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“hue”</td> <td>RANGE</td> <td>Min=0, Max=359</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“saturation”</td> <td>RANGE</td> <td>Min=0, Max=8192-1</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“iturbt_709”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>Nv04 Overlay</td> <td>“colorkey”</td> <td>RANGE</td> <td>Min=0, Max=0x01ffffff</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“brightness”</td> <td>RANGE</td> <td>Min=0, Max=1024</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>Display</td> <td>“dithering mode”</td> <td>ENUM</td> <td>{ “auto”, “off”, “on” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“dithering depth”</td> <td>ENUM</td> <td>{ “auto”, “off”, “on”, “static 2x2”, “dynamic 2x2”, “temporal” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“underscan”</td> <td>ENUM</td> <td>{ “auto”, “6 bpc”, “8 bpc” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“underscan hborder”</td> <td>RANGE</td> <td>Min=0, Max=128</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“underscan vborder”</td> <td>RANGE</td> <td>Min=0, Max=128</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“vibrant hue”</td> <td>RANGE</td> <td>Min=0, Max=180</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“color vibrance”</td> <td>RANGE</td> <td>Min=0, Max=200</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td>omap</td> <td>Generic</td> <td>“zorder”</td> <td>RANGE</td> <td>Min=0, Max=3</td> <td>CRTC, Plane</td> <td>TBD</td> </tr> <tr class="row-even"><td>qxl</td> <td>Generic</td> <td>“hotplug_mode_update”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td>radeon</td> <td>DVI-I</td> <td>“coherent”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>DAC enable load detect</td> <td>“load detection”</td> <td>RANGE</td> <td>Min=0, Max=1</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>TV Standard</td> <td>“tv standard”</td> <td>ENUM</td> <td>{ “ntsc”, “pal”, “pal-m”, “pal-60”, “ntsc-j” , “scart-pal”, “pal-cn”, “secam” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>legacy TMDS PLL detect</td> <td>“tmds_pll”</td> <td>ENUM</td> <td>{ “driver”, “bios” }</td> <td><ul class="first last simple"> <li></li> </ul> </td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>Underscan</td> <td>“underscan”</td> <td>ENUM</td> <td>{ “off”, “on”, “auto” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td> </td> <td>“underscan hborder”</td> <td>RANGE</td> <td>Min=0, Max=128</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“underscan vborder”</td> <td>RANGE</td> <td>Min=0, Max=128</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td> </td> <td>Audio</td> <td>“audio”</td> <td>ENUM</td> <td>{ “off”, “on”, “auto” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td>FMT Dithering</td> <td>“dither”</td> <td>ENUM</td> <td>{ “off”, “on” }</td> <td>Connector</td> <td>TBD</td> </tr> <tr class="row-even"><td>rcar-du</td> <td>Generic</td> <td>“alpha”</td> <td>RANGE</td> <td>Min=0, Max=255</td> <td>Plane</td> <td>TBD</td> </tr> <tr class="row-odd"><td> </td> <td> </td> <td>“colorkey”</td> <td>RANGE</td> <td>Min=0, Max=0x01ffffff</td> <td>Plane</td> <td>TBD</td> </tr> </tbody> </table> </div> </div> <div class="section" id="vertical-blanking"> <h2>Vertical Blanking<a class="headerlink" href="#vertical-blanking" title="Permalink to this headline">¶</a></h2> Vertical blanking plays a major role in graphics rendering. To achieve tear-free display, users must synchronize page flips and/or rendering to vertical blanking. The DRM API offers ioctls to perform page flips synchronized to vertical blanking and wait for vertical blanking. The DRM core handles most of the vertical blanking management logic, which involves filtering out spurious interrupts, keeping race-free blanking counters, coping with counter wrap-around and resets and keeping use counts. It relies on the driver to generate vertical blanking interrupts and optionally provide a hardware vertical blanking counter. Drivers must initialize the vertical blanking handling core with a call to <a class="reference internal" href="#c.drm_vblank_init" title="drm_vblank_init"><code class="xref c c-func docutils literal">drm_vblank_init()</code></a>. Minimally, a driver needs to implement <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.enable_vblank</code></a> and <a class="reference internal" href="#c.drm_crtc_funcs" title="drm_crtc_funcs"><code class="xref c c-type docutils literal">drm_crtc_funcs.disable_vblank</code></a> plus call <a class="reference internal" href="#c.drm_crtc_handle_vblank" title="drm_crtc_handle_vblank"><code class="xref c c-func docutils literal">drm_crtc_handle_vblank()</code></a> in it’s vblank interrupt handler for working vblank support. Vertical blanking interrupts can be enabled by the DRM core or by drivers themselves (for instance to handle page flipping operations). The DRM core maintains a vertical blanking use count to ensure that the interrupts are not disabled while a user still needs them. To increment the use count, drivers call <a class="reference internal" href="#c.drm_crtc_vblank_get" title="drm_crtc_vblank_get"><code class="xref c c-func docutils literal">drm_crtc_vblank_get()</code></a> and release the vblank reference again with <a class="reference internal" href="#c.drm_crtc_vblank_put" title="drm_crtc_vblank_put"><code class="xref c c-func docutils literal">drm_crtc_vblank_put()</code></a>. In between these two calls vblank interrupts are guaranteed to be enabled. On many hardware disabling the vblank interrupt cannot be done in a race-free manner, see <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.vblank_disable_immediate</code></a> and <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.max_vblank_count</code></a>. In that case the vblank core only disables the vblanks after a timer has expired, which can be configured through the <code class="docutils literal">vblankoffdelay</code> module parameter. <div class="section" id="vertical-blanking-and-interrupt-handling-functions-reference"> <h3>Vertical Blanking and Interrupt Handling Functions Reference<a class="headerlink" href="#vertical-blanking-and-interrupt-handling-functions-reference" title="Permalink to this headline">¶</a></h3> <dl class="type"> <dt id="c.drm_pending_vblank_event"> struct <code class="descname">drm_pending_vblank_event</code><a class="headerlink" href="#c.drm_pending_vblank_event" title="Permalink to this definition">¶</a></dt> <dd>pending vblank event tracking </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_pending_vblank_event { struct drm_pending_event base; unsigned int pipe; u64 sequence; union { struct drm_event base; struct drm_event_vblank vbl; struct drm_event_crtc_sequence seq; } event; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">base</code></dt> <dd>Base structure for tracking pending DRM events.</dd> <dt><code class="docutils literal">pipe</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_index" title="drm_crtc_index"><code class="xref c c-func docutils literal">drm_crtc_index()</code></a> of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> this event is for.</dd> <dt><code class="docutils literal">sequence</code></dt> <dd>frame event should be triggered at</dd> <dt><code class="docutils literal">event</code></dt> <dd>Actual event which will be sent to userspace.</dd> </dl> <dl class="type"> <dt id="c.drm_vblank_crtc"> struct <code class="descname">drm_vblank_crtc</code><a class="headerlink" href="#c.drm_vblank_crtc" title="Permalink to this definition">¶</a></dt> <dd>vblank tracking for a CRTC </dd></dl> Definition <div class="highlight-none"><div class="highlight"><pre>struct drm_vblank_crtc { struct drm_device *dev; wait_queue_head_t queue; struct timer_list disable_timer; seqlock_t seqlock; u64 count; ktime_t time; atomic_t refcount; u32 last; unsigned int inmodeset; unsigned int pipe; int framedur_ns; int linedur_ns; struct drm_display_mode hwmode; bool enabled; }; </pre></div> </div> Members <dl class="docutils"> <dt><code class="docutils literal">dev</code></dt> <dd>Pointer to the <code class="xref c c-type docutils literal">drm_device</code>.</dd> <dt><code class="docutils literal">queue</code></dt> <dd>Wait queue for vblank waiters.</dd> <dt><code class="docutils literal">disable_timer</code></dt> <dd>Disable timer for the delayed vblank disabling hysteresis logic. Vblank disabling is controlled through the drm_vblank_offdelay module option and the setting of the <code class="xref c c-type docutils literal">drm_device.max_vblank_count</code> value.</dd> <dt><code class="docutils literal">seqlock</code></dt> <dd>Protect vblank count and time.</dd> <dt><code class="docutils literal">count</code></dt> <dd>Current software vblank counter.</dd> <dt><code class="docutils literal">time</code></dt> <dd>Vblank timestamp corresponding to count.</dd> <dt><code class="docutils literal">refcount</code></dt> <dd>Number of users/waiters of the vblank interrupt. Only when this refcount reaches 0 can the hardware interrupt be disabled using disable_timer.</dd> <dt><code class="docutils literal">last</code></dt> <dd>Protected by <code class="xref c c-type docutils literal">drm_device.vbl_lock</code>, used for wraparound handling.</dd> <dt><code class="docutils literal">inmodeset</code></dt> <dd>Tracks whether the vblank is disabled due to a modeset. For legacy driver bit 2 additionally tracks whether an additional temporary vblank reference has been acquired to paper over the hardware counter resetting/jumping. KMS drivers should instead just call <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> and <a class="reference internal" href="#c.drm_crtc_vblank_on" title="drm_crtc_vblank_on"><code class="xref c c-func docutils literal">drm_crtc_vblank_on()</code></a>, which explicitly save and restore the vblank count.</dd> <dt><code class="docutils literal">pipe</code></dt> <dd><a class="reference internal" href="#c.drm_crtc_index" title="drm_crtc_index"><code class="xref c c-func docutils literal">drm_crtc_index()</code></a> of the <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> corresponding to this structure.</dd> <dt><code class="docutils literal">framedur_ns</code></dt> <dd>Frame/Field duration in ns, used by <a class="reference internal" href="#c.drm_calc_vbltimestamp_from_scanoutpos" title="drm_calc_vbltimestamp_from_scanoutpos"><code class="xref c c-func docutils literal">drm_calc_vbltimestamp_from_scanoutpos()</code></a> and computed by <a class="reference internal" href="#c.drm_calc_timestamping_constants" title="drm_calc_timestamping_constants"><code class="xref c c-func docutils literal">drm_calc_timestamping_constants()</code></a>.</dd> <dt><code class="docutils literal">linedur_ns</code></dt> <dd>Line duration in ns, used by <a class="reference internal" href="#c.drm_calc_vbltimestamp_from_scanoutpos" title="drm_calc_vbltimestamp_from_scanoutpos"><code class="xref c c-func docutils literal">drm_calc_vbltimestamp_from_scanoutpos()</code></a> and computed by <a class="reference internal" href="#c.drm_calc_timestamping_constants" title="drm_calc_timestamping_constants"><code class="xref c c-func docutils literal">drm_calc_timestamping_constants()</code></a>.</dd> <dt><code class="docutils literal">hwmode</code></dt> <dd>Cache of the current hardware display mode. Only valid when enabled is set. This is used by helpers like <a class="reference internal" href="#c.drm_calc_vbltimestamp_from_scanoutpos" title="drm_calc_vbltimestamp_from_scanoutpos"><code class="xref c c-func docutils literal">drm_calc_vbltimestamp_from_scanoutpos()</code></a>. We can’t just access the hardware mode by e.g. looking at <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.adjusted_mode</code></a>, because that one is really hard to get from interrupt context.</dd> <dt><code class="docutils literal">enabled</code></dt> <dd>Tracks the enabling state of the corresponding <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">drm_crtc</code></a> to avoid double-disabling and hence corrupting saved state. Needed by drivers not using atomic KMS, since those might go through their CRTC disabling functions multiple times.</dd> </dl> Description This structure tracks the vblank state for one CRTC. Note that for historical reasons - the vblank handling code is still shared with legacy/non-kms drivers - this is a free-standing structure not directly connected to <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a>. But all public interface functions are taking a <a class="reference internal" href="#c.drm_crtc" title="drm_crtc"><code class="xref c c-type docutils literal">struct drm_crtc</code></a> to hide this implementation detail. <dl class="function"> <dt id="c.drm_crtc_accurate_vblank_count"> u32 <code class="descname">drm_crtc_accurate_vblank_count</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_accurate_vblank_count" title="Permalink to this definition">¶</a></dt> <dd>retrieve the master vblank counter </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which counter to retrieve</dd> </dl> Description This function is similar to <a class="reference internal" href="#c.drm_crtc_vblank_count" title="drm_crtc_vblank_count"><code class="xref c c-func docutils literal">drm_crtc_vblank_count()</code></a> but this function interpolates to handle a race with vblank interrupts using the high precision timestamping support. This is mostly useful for hardware that can obtain the scanout position, but doesn’t have a hardware frame counter. <dl class="function"> <dt id="c.drm_vblank_init"> int <code class="descname">drm_vblank_init</code>(struct drm_device * dev, unsigned int num_crtcs)<a class="headerlink" href="#c.drm_vblank_init" title="Permalink to this definition">¶</a></dt> <dd>initialize vblank support </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">unsigned int num_crtcs</code></dt> <dd>number of CRTCs supported by dev</dd> </dl> Description This function initializes vblank support for num_crtcs display pipelines. Cleanup is handled by the DRM core, or through calling <a class="reference internal" href="drm-internals.html#c.drm_dev_fini" title="drm_dev_fini"><code class="xref c c-func docutils literal">drm_dev_fini()</code></a> for drivers with a <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.release</code></a> callback. Return Zero on success or a negative error code on failure. <dl class="function"> <dt id="c.drm_crtc_vblank_waitqueue"> wait_queue_head_t * <code class="descname">drm_crtc_vblank_waitqueue</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_waitqueue" title="Permalink to this definition">¶</a></dt> <dd>get vblank waitqueue for the CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which CRTC’s vblank waitqueue to retrieve</dd> </dl> Description This function returns a pointer to the vblank waitqueue for the CRTC. Drivers can use this to implement vblank waits using <a class="reference internal" href="../driver-api/basics.html#c.wait_event" title="wait_event"><code class="xref c c-func docutils literal">wait_event()</code></a> and related functions. <dl class="function"> <dt id="c.drm_calc_timestamping_constants"> void <code class="descname">drm_calc_timestamping_constants</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, const struct <a class="reference internal" href="#c.drm_display_mode" title="drm_display_mode">drm_display_mode</a> * mode)<a class="headerlink" href="#c.drm_calc_timestamping_constants" title="Permalink to this definition">¶</a></dt> <dd>calculate vblank timestamp constants </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>drm_crtc whose timestamp constants should be updated.</dd> <dt><code class="docutils literal">const struct drm_display_mode * mode</code></dt> <dd>display mode containing the scanout timings</dd> </dl> Description Calculate and store various constants which are later needed by vblank and swap-completion timestamping, e.g, by <a class="reference internal" href="#c.drm_calc_vbltimestamp_from_scanoutpos" title="drm_calc_vbltimestamp_from_scanoutpos"><code class="xref c c-func docutils literal">drm_calc_vbltimestamp_from_scanoutpos()</code></a>. They are derived from CRTC’s true scanout timing, so they take things like panel scaling or other adjustments into account. <dl class="function"> <dt id="c.drm_calc_vbltimestamp_from_scanoutpos"> bool <code class="descname">drm_calc_vbltimestamp_from_scanoutpos</code>(struct drm_device * dev, unsigned int pipe, int * max_error, ktime_t * vblank_time, bool in_vblank_irq)<a class="headerlink" href="#c.drm_calc_vbltimestamp_from_scanoutpos" title="Permalink to this definition">¶</a></dt> <dd>precise vblank timestamp helper </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">unsigned int pipe</code></dt> <dd>index of CRTC whose vblank timestamp to retrieve</dd> <dt><code class="docutils literal">int * max_error</code></dt> <dd>Desired maximum allowable error in timestamps (nanosecs) On return contains true maximum error of timestamp</dd> <dt><code class="docutils literal">ktime_t * vblank_time</code></dt> <dd>Pointer to time which should receive the timestamp</dd> <dt><code class="docutils literal">bool in_vblank_irq</code></dt> <dd>True when called from <a class="reference internal" href="#c.drm_crtc_handle_vblank" title="drm_crtc_handle_vblank"><code class="xref c c-func docutils literal">drm_crtc_handle_vblank()</code></a>. Some drivers need to apply some workarounds for gpu-specific vblank irq quirks if flag is set.</dd> </dl> Description Implements calculation of exact vblank timestamps from given drm_display_mode timings and current video scanout position of a CRTC. This can be directly used as the <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.get_vblank_timestamp</code></a> implementation of a kms driver if <a class="reference internal" href="drm-internals.html#c.drm_driver" title="drm_driver"><code class="xref c c-type docutils literal">drm_driver.get_scanout_position</code></a> is implemented. The current implementation only handles standard video modes. For double scan and interlaced modes the driver is supposed to adjust the hardware mode (taken from <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.adjusted</code></a> mode for atomic modeset drivers) to match the scanout position reported. Note that atomic drivers must call <a class="reference internal" href="#c.drm_calc_timestamping_constants" title="drm_calc_timestamping_constants"><code class="xref c c-func docutils literal">drm_calc_timestamping_constants()</code></a> before enabling a CRTC. The atomic helpers already take care of that in <a class="reference internal" href="drm-kms-helpers.html#c.drm_atomic_helper_update_legacy_modeset_state" title="drm_atomic_helper_update_legacy_modeset_state"><code class="xref c c-func docutils literal">drm_atomic_helper_update_legacy_modeset_state()</code></a>. Return Returns true on success, and false on failure, i.e. when no accurate timestamp could be acquired. <dl class="function"> <dt id="c.drm_crtc_vblank_count"> u64 <code class="descname">drm_crtc_vblank_count</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_count" title="Permalink to this definition">¶</a></dt> <dd>retrieve “cooked” vblank counter value </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which counter to retrieve</dd> </dl> Description Fetches the “cooked” vblank count value that represents the number of vblank events since the system was booted, including lost events due to modesetting activity. Note that this timer isn’t correct against a racing vblank interrupt (since it only reports the software vblank counter), see <a class="reference internal" href="#c.drm_crtc_accurate_vblank_count" title="drm_crtc_accurate_vblank_count"><code class="xref c c-func docutils literal">drm_crtc_accurate_vblank_count()</code></a> for such use-cases. Return The software vblank counter. <dl class="function"> <dt id="c.drm_crtc_vblank_count_and_time"> u64 <code class="descname">drm_crtc_vblank_count_and_time</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, ktime_t * vblanktime)<a class="headerlink" href="#c.drm_crtc_vblank_count_and_time" title="Permalink to this definition">¶</a></dt> <dd>retrieve “cooked” vblank counter value and the system timestamp corresponding to that vblank counter value </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which counter to retrieve</dd> <dt><code class="docutils literal">ktime_t * vblanktime</code></dt> <dd>Pointer to time to receive the vblank timestamp.</dd> </dl> Description Fetches the “cooked” vblank count value that represents the number of vblank events since the system was booted, including lost events due to modesetting activity. Returns corresponding system timestamp of the time of the vblank interval that corresponds to the current vblank counter value. <dl class="function"> <dt id="c.drm_crtc_arm_vblank_event"> void <code class="descname">drm_crtc_arm_vblank_event</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, struct <a class="reference internal" href="#c.drm_pending_vblank_event" title="drm_pending_vblank_event">drm_pending_vblank_event</a> * e)<a class="headerlink" href="#c.drm_crtc_arm_vblank_event" title="Permalink to this definition">¶</a></dt> <dd>arm vblank event after pageflip </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>the source CRTC of the vblank event</dd> <dt><code class="docutils literal">struct drm_pending_vblank_event * e</code></dt> <dd>the event to send</dd> </dl> Description A lot of drivers need to generate vblank events for the very next vblank interrupt. For example when the page flip interrupt happens when the page flip gets armed, but not when it actually executes within the next vblank period. This helper function implements exactly the required vblank arming behaviour. NOTE Drivers using this to send out the <a class="reference internal" href="#c.drm_crtc_state" title="drm_crtc_state"><code class="xref c c-type docutils literal">drm_crtc_state.event</code></a> as part of an atomic commit must ensure that the next vblank happens at exactly the same time as the atomic commit is committed to the hardware. This function itself does not protect against the next vblank interrupt racing with either this function call or the atomic commit operation. A possible sequence could be: <ol class="arabic simple"> <li>Driver commits new hardware state into vblank-synchronized registers.</li> <li>A vblank happens, committing the hardware state. Also the corresponding vblank interrupt is fired off and fully processed by the interrupt handler.</li> <li>The atomic commit operation proceeds to call <a class="reference internal" href="#c.drm_crtc_arm_vblank_event" title="drm_crtc_arm_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_arm_vblank_event()</code></a>.</li> <li>The event is only send out for the next vblank, which is wrong.</li> </ol> An equivalent race can happen when the driver calls <a class="reference internal" href="#c.drm_crtc_arm_vblank_event" title="drm_crtc_arm_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_arm_vblank_event()</code></a> before writing out the new hardware state. The only way to make this work safely is to prevent the vblank from firing (and the hardware from committing anything else) until the entire atomic commit sequence has run to completion. If the hardware does not have such a feature (e.g. using a “go” bit), then it is unsafe to use this functions. Instead drivers need to manually send out the event from their interrupt handler by calling <a class="reference internal" href="#c.drm_crtc_send_vblank_event" title="drm_crtc_send_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_send_vblank_event()</code></a> and make sure that there’s no possible race with the hardware committing the atomic update. Caller must hold a vblank reference for the event e, which will be dropped when the next vblank arrives. <dl class="function"> <dt id="c.drm_crtc_send_vblank_event"> void <code class="descname">drm_crtc_send_vblank_event</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc, struct <a class="reference internal" href="#c.drm_pending_vblank_event" title="drm_pending_vblank_event">drm_pending_vblank_event</a> * e)<a class="headerlink" href="#c.drm_crtc_send_vblank_event" title="Permalink to this definition">¶</a></dt> <dd>helper to send vblank event after pageflip </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>the source CRTC of the vblank event</dd> <dt><code class="docutils literal">struct drm_pending_vblank_event * e</code></dt> <dd>the event to send</dd> </dl> Description Updates sequence # and timestamp on event for the most recently processed vblank, and sends it to userspace. Caller must hold event lock. See <a class="reference internal" href="#c.drm_crtc_arm_vblank_event" title="drm_crtc_arm_vblank_event"><code class="xref c c-func docutils literal">drm_crtc_arm_vblank_event()</code></a> for a helper which can be used in certain situation, especially to send out events for atomic commit operations. <dl class="function"> <dt id="c.drm_crtc_vblank_get"> int <code class="descname">drm_crtc_vblank_get</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_get" title="Permalink to this definition">¶</a></dt> <dd>get a reference count on vblank events </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which CRTC to own</dd> </dl> Description Acquire a reference count on vblank events to avoid having them disabled while in use. Return Zero on success or a negative error code on failure. <dl class="function"> <dt id="c.drm_crtc_vblank_put"> void <code class="descname">drm_crtc_vblank_put</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_put" title="Permalink to this definition">¶</a></dt> <dd>give up ownership of vblank events </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>which counter to give up</dd> </dl> Description Release ownership of a given vblank counter, turning off interrupts if possible. Disable interrupts after drm_vblank_offdelay milliseconds. <dl class="function"> <dt id="c.drm_wait_one_vblank"> void <code class="descname">drm_wait_one_vblank</code>(struct drm_device * dev, unsigned int pipe)<a class="headerlink" href="#c.drm_wait_one_vblank" title="Permalink to this definition">¶</a></dt> <dd>wait for one vblank </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">unsigned int pipe</code></dt> <dd>CRTC index</dd> </dl> Description This waits for one vblank to pass on pipe, using the irq driver interfaces. It is a failure to call this when the vblank irq for pipe is disabled, e.g. due to lack of driver support or because the crtc is off. This is the legacy version of <a class="reference internal" href="#c.drm_crtc_wait_one_vblank" title="drm_crtc_wait_one_vblank"><code class="xref c c-func docutils literal">drm_crtc_wait_one_vblank()</code></a>. <dl class="function"> <dt id="c.drm_crtc_wait_one_vblank"> void <code class="descname">drm_crtc_wait_one_vblank</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_wait_one_vblank" title="Permalink to this definition">¶</a></dt> <dd>wait for one vblank </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>DRM crtc</dd> </dl> Description This waits for one vblank to pass on crtc, using the irq driver interfaces. It is a failure to call this when the vblank irq for crtc is disabled, e.g. due to lack of driver support or because the crtc is off. <dl class="function"> <dt id="c.drm_crtc_vblank_off"> void <code class="descname">drm_crtc_vblank_off</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_off" title="Permalink to this definition">¶</a></dt> <dd>disable vblank events on a CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC in question</dd> </dl> Description Drivers can use this function to shut down the vblank interrupt handling when disabling a crtc. This function ensures that the latest vblank frame count is stored so that drm_vblank_on can restore it again. Drivers must use this function when the hardware vblank counter can get reset, e.g. when suspending or disabling the crtc in general. <dl class="function"> <dt id="c.drm_crtc_vblank_reset"> void <code class="descname">drm_crtc_vblank_reset</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_reset" title="Permalink to this definition">¶</a></dt> <dd>reset vblank state to off on a CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC in question</dd> </dl> Description Drivers can use this function to reset the vblank state to off at load time. Drivers should use this together with the <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> and <a class="reference internal" href="#c.drm_crtc_vblank_on" title="drm_crtc_vblank_on"><code class="xref c c-func docutils literal">drm_crtc_vblank_on()</code></a> functions. The difference compared to <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> is that this function doesn’t save the vblank counter and hence doesn’t need to call any driver hooks. This is useful for recovering driver state e.g. on driver load, or on resume. <dl class="function"> <dt id="c.drm_crtc_vblank_on"> void <code class="descname">drm_crtc_vblank_on</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_vblank_on" title="Permalink to this definition">¶</a></dt> <dd>enable vblank events on a CRTC </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>CRTC in question</dd> </dl> Description This functions restores the vblank interrupt state captured with <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> again and is generally called when enabling crtc. Note that calls to <a class="reference internal" href="#c.drm_crtc_vblank_on" title="drm_crtc_vblank_on"><code class="xref c c-func docutils literal">drm_crtc_vblank_on()</code></a> and <a class="reference internal" href="#c.drm_crtc_vblank_off" title="drm_crtc_vblank_off"><code class="xref c c-func docutils literal">drm_crtc_vblank_off()</code></a> can be unbalanced and so can also be unconditionally called in driver load code to reflect the current hardware state of the crtc. <dl class="function"> <dt id="c.drm_handle_vblank"> bool <code class="descname">drm_handle_vblank</code>(struct drm_device * dev, unsigned int pipe)<a class="headerlink" href="#c.drm_handle_vblank" title="Permalink to this definition">¶</a></dt> <dd>handle a vblank event </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_device * dev</code></dt> <dd>DRM device</dd> <dt><code class="docutils literal">unsigned int pipe</code></dt> <dd>index of CRTC where this event occurred</dd> </dl> Description Drivers should call this routine in their vblank interrupt handlers to update the vblank counter and send any signals that may be pending. This is the legacy version of <a class="reference internal" href="#c.drm_crtc_handle_vblank" title="drm_crtc_handle_vblank"><code class="xref c c-func docutils literal">drm_crtc_handle_vblank()</code></a>. <dl class="function"> <dt id="c.drm_crtc_handle_vblank"> bool <code class="descname">drm_crtc_handle_vblank</code>(struct <a class="reference internal" href="#c.drm_crtc" title="drm_crtc">drm_crtc</a> * crtc)<a class="headerlink" href="#c.drm_crtc_handle_vblank" title="Permalink to this definition">¶</a></dt> <dd>handle a vblank event </dd></dl> Parameters <dl class="docutils"> <dt><code class="docutils literal">struct drm_crtc * crtc</code></dt> <dd>where this event occurred</dd> </dl> Description Drivers should call this routine in their vblank interrupt handlers to update the vblank counter and send any signals that may be pending. This is the native KMS version of <a class="reference internal" href="#c.drm_handle_vblank" title="drm_handle_vblank"><code class="xref c c-func docutils literal">drm_handle_vblank()</code></a>. Return True if the event was successfully handled, false on failure. </div> </div> </div> </div> <div class="articleComments"> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="drm-kms-helpers.html" class="btn btn-neutral float-right" title="Mode Setting Helper Functions" accesskey="n" rel="next">Next </a> <a href="drm-mm.html" class="btn btn-neutral" title="DRM Memory Management" accesskey="p" rel="prev"> Previous</a> </div> <hr/> <div role="contentinfo"> © Copyright The kernel development community. </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT:'../', VERSION:'', COLLAPSE_INDEX:false, FILE_SUFFIX:'.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '' }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/js/theme.js"></script> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.StickyNav.enable(); }); </script> </body> </html>