1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>KMS Initialization and Cleanup</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux DRM Developer's Guide"><link rel="up" href="drmInternals.html" title="Chapter 2. DRM Internals"><link rel="prev" href="API-drm-atomic-async-commit.html" title="drm_atomic_async_commit"><link rel="next" href="API-drm-get-connector-status-name.html" title="drm_get_connector_status_name"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">KMS Initialization and Cleanup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-drm-atomic-async-commit.html">Prev</a> </td><th width="60%" align="center">Chapter 2. DRM Internals</th><td width="20%" align="right"> <a accesskey="n" href="API-drm-get-connector-status-name.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="drm-kms-init"></a>KMS Initialization and Cleanup</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="drm-kms-init.html#idp1123813300">CRTCs (struct <span class="structname">drm_crtc</span>)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123834892">Planes (struct <span class="structname">drm_plane</span>)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123849172">Encoders (struct <span class="structname">drm_encoder</span>)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123859012">Connectors (struct <span class="structname">drm_connector</span>)</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123892868">Cleanup</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123897460">Output discovery and initialization example</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1123898740">KMS API Functions</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1124538092">KMS Data Structures</a></span></dt><dt><span class="sect2"><a href="drm-kms-init.html#idp1124843020">KMS Locking</a></span></dt></dl></div><p> 2 A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders 3 and connectors. KMS drivers must thus create and initialize all those 4 objects at load time after initializing mode setting. 5 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123813300"></a>CRTCs (struct <span class="structname">drm_crtc</span>)</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect3"><a href="drm-kms-init.html#idp1123814556">CRTC Initialization</a></span></dt><dt><span class="sect3"><a href="drm-kms-init.html#drm-kms-crtcops">CRTC Operations</a></span></dt></dl></div><p> 6 A CRTC is an abstraction representing a part of the chip that contains a 7 pointer to a scanout buffer. Therefore, the number of CRTCs available 8 determines how many independent scanout buffers can be active at any 9 given time. The CRTC structure contains several fields to support this: 10 a pointer to some video memory (abstracted as a frame buffer object), a 11 display mode, and an (x, y) offset into the video memory to support 12 panning or configurations where one piece of video memory spans multiple 13 CRTCs. 14 </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123814556"></a>CRTC Initialization</h4></div></div></div><p> 15 A KMS device must create and register at least one struct 16 <span class="structname">drm_crtc</span> instance. The instance is allocated 17 and zeroed by the driver, possibly as part of a larger structure, and 18 registered with a call to <code class="function">drm_crtc_init</code> with a 19 pointer to CRTC functions. 20 </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="drm-kms-crtcops"></a>CRTC Operations</h4></div></div></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123816588"></a>Set Configuration</h5></div></div></div><pre class="synopsis">int (*set_config)(struct drm_mode_set *set);</pre><p> 21 Apply a new CRTC configuration to the device. The configuration 22 specifies a CRTC, a frame buffer to scan out from, a (x,y) position in 23 the frame buffer, a display mode and an array of connectors to drive 24 with the CRTC if possible. 25 </p><p> 26 If the frame buffer specified in the configuration is NULL, the driver 27 must detach all encoders connected to the CRTC and all connectors 28 attached to those encoders and disable them. 29 </p><p> 30 This operation is called with the mode config lock held. 31 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 32 Note that the drm core has no notion of restoring the mode setting 33 state after resume, since all resume handling is in the full 34 responsibility of the driver. The common mode setting helper library 35 though provides a helper which can be used for this: 36 <code class="function">drm_helper_resume_force_mode</code>. 37 </p></div></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123819524"></a>Page Flipping</h5></div></div></div><pre class="synopsis">int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, 38 struct drm_pending_vblank_event *event);</pre><p> 39 Schedule a page flip to the given frame buffer for the CRTC. This 40 operation is called with the mode config mutex held. 41 </p><p> 42 Page flipping is a synchronization mechanism that replaces the frame 43 buffer being scanned out by the CRTC with a new frame buffer during 44 vertical blanking, avoiding tearing. When an application requests a page 45 flip the DRM core verifies that the new frame buffer is large enough to 46 be scanned out by the CRTC in the currently configured mode and then 47 calls the CRTC <code class="methodname">page_flip</code> operation with a 48 pointer to the new frame buffer. 49 </p><p> 50 The <code class="methodname">page_flip</code> operation schedules a page flip. 51 Once any pending rendering targeting the new frame buffer has 52 completed, the CRTC will be reprogrammed to display that frame buffer 53 after the next vertical refresh. The operation must return immediately 54 without waiting for rendering or page flip to complete and must block 55 any new rendering to the frame buffer until the page flip completes. 56 </p><p> 57 If a page flip can be successfully scheduled the driver must set the 58 <code class="code">drm_crtc->fb</code> field to the new framebuffer pointed to 59 by <code class="code">fb</code>. This is important so that the reference counting 60 on framebuffers stays balanced. 61 </p><p> 62 If a page flip is already pending, the 63 <code class="methodname">page_flip</code> operation must return 64 -<span class="errorname">EBUSY</span>. 65 </p><p> 66 To synchronize page flip to vertical blanking the driver will likely 67 need to enable vertical blanking interrupts. It should call 68 <code class="function">drm_vblank_get</code> for that purpose, and call 69 <code class="function">drm_vblank_put</code> after the page flip completes. 70 </p><p> 71 If the application has requested to be notified when page flip completes 72 the <code class="methodname">page_flip</code> operation will be called with a 73 non-NULL <em class="parameter"><code>event</code></em> argument pointing to a 74 <span class="structname">drm_pending_vblank_event</span> instance. Upon page 75 flip completion the driver must call <code class="methodname">drm_send_vblank_event</code> 76 to fill in the event and send to wake up any waiting processes. 77 This can be performed with 78 </p><pre class="programlisting"> 79 spin_lock_irqsave(&dev->event_lock, flags); 80 ... 81 drm_send_vblank_event(dev, pipe, event); 82 spin_unlock_irqrestore(&dev->event_lock, flags); 83 </pre><p> 84 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 85 FIXME: Could drivers that don't need to wait for rendering to complete 86 just add the event to <code class="literal">dev->vblank_event_list</code> and 87 let the DRM core handle everything, as for "normal" vertical blanking 88 events? 89 </p></div><p> 90 While waiting for the page flip to complete, the 91 <code class="literal">event->base.link</code> list head can be used freely by 92 the driver to store the pending event in a driver-specific list. 93 </p><p> 94 If the file handle is closed before the event is signaled, drivers must 95 take care to destroy the event in their 96 <code class="methodname">preclose</code> operation (and, if needed, call 97 <code class="function">drm_vblank_put</code>). 98 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123830236"></a>Miscellaneous</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">void (*set_property)(struct drm_crtc *crtc, 99 struct drm_property *property, uint64_t value);</pre><p> 100 Set the value of the given CRTC property to 101 <em class="parameter"><code>value</code></em>. See <a class="xref" href="drm-kms-properties.html" title="KMS Properties">the section called “KMS Properties”</a> 102 for more information about properties. 103 </p></li><li class="listitem"><pre class="synopsis">void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, 104 uint32_t start, uint32_t size);</pre><p> 105 Apply a gamma table to the device. The operation is optional. 106 </p></li><li class="listitem"><pre class="synopsis">void (*destroy)(struct drm_crtc *crtc);</pre><p> 107 Destroy the CRTC when not needed anymore. See 108 <a class="xref" href="drm-kms-init.html" title="KMS Initialization and Cleanup">the section called “KMS Initialization and Cleanup”</a>. 109 </p></li></ul></div></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123834892"></a>Planes (struct <span class="structname">drm_plane</span>)</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect3"><a href="drm-kms-init.html#idp1123838324">Plane Initialization</a></span></dt><dt><span class="sect3"><a href="drm-kms-init.html#idp1123841012">Plane Operations</a></span></dt></dl></div><p> 110 A plane represents an image source that can be blended with or overlayed 111 on top of a CRTC during the scanout process. Planes are associated with 112 a frame buffer to crop a portion of the image memory (source) and 113 optionally scale it to a destination size. The result is then blended 114 with or overlayed on top of a CRTC. 115 </p><p> 116 The DRM core recognizes three types of planes: 117 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 118 DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary 119 planes are the planes operated upon by CRTC modesetting and flipping 120 operations described in <a class="xref" href="drm-kms-init.html#drm-kms-crtcops" title="CRTC Operations">the section called “CRTC Operations”</a>. 121 </li><li class="listitem"> 122 DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor 123 planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and 124 DRM_IOCTL_MODE_CURSOR2 ioctls. 125 </li><li class="listitem"> 126 DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. 127 Some drivers refer to these types of planes as "sprites" internally. 128 </li></ul></div><p> 129 For compatibility with legacy userspace, only overlay planes are made 130 available to userspace by default. Userspace clients may set the 131 DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that 132 they wish to receive a universal plane list containing all plane types. 133 </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123838324"></a>Plane Initialization</h4></div></div></div><p> 134 To create a plane, a KMS drivers allocates and 135 zeroes an instances of struct <span class="structname">drm_plane</span> 136 (possibly as part of a larger structure) and registers it with a call 137 to <code class="function">drm_universal_plane_init</code>. The function takes a bitmask 138 of the CRTCs that can be associated with the plane, a pointer to the 139 plane functions, a list of format supported formats, and the type of 140 plane (primary, cursor, or overlay) being initialized. 141 </p><p> 142 Cursor and overlay planes are optional. All drivers should provide 143 one primary plane per CRTC (although this requirement may change in 144 the future); drivers that do not wish to provide special handling for 145 primary planes may make use of the helper functions described in 146 <a class="xref" href="ch02s05.html#drm-kms-planehelpers">the section called “Plane Helper Reference”</a> to create and register a 147 primary plane with standard capabilities. 148 </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123841012"></a>Plane Operations</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, 149 struct drm_framebuffer *fb, int crtc_x, int crtc_y, 150 unsigned int crtc_w, unsigned int crtc_h, 151 uint32_t src_x, uint32_t src_y, 152 uint32_t src_w, uint32_t src_h);</pre><p> 153 Enable and configure the plane to use the given CRTC and frame buffer. 154 </p><p> 155 The source rectangle in frame buffer memory coordinates is given by 156 the <em class="parameter"><code>src_x</code></em>, <em class="parameter"><code>src_y</code></em>, 157 <em class="parameter"><code>src_w</code></em> and <em class="parameter"><code>src_h</code></em> 158 parameters (as 16.16 fixed point values). Devices that don't support 159 subpixel plane coordinates can ignore the fractional part. 160 </p><p> 161 The destination rectangle in CRTC coordinates is given by the 162 <em class="parameter"><code>crtc_x</code></em>, <em class="parameter"><code>crtc_y</code></em>, 163 <em class="parameter"><code>crtc_w</code></em> and <em class="parameter"><code>crtc_h</code></em> 164 parameters (as integer values). Devices scale the source rectangle to 165 the destination rectangle. If scaling is not supported, and the source 166 rectangle size doesn't match the destination rectangle size, the 167 driver must return a -<span class="errorname">EINVAL</span> error. 168 </p></li><li class="listitem"><pre class="synopsis">int (*disable_plane)(struct drm_plane *plane);</pre><p> 169 Disable the plane. The DRM core calls this method in response to a 170 DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. 171 Disabled planes must not be processed by the CRTC. 172 </p></li><li class="listitem"><pre class="synopsis">void (*destroy)(struct drm_plane *plane);</pre><p> 173 Destroy the plane when not needed anymore. See 174 <a class="xref" href="drm-kms-init.html" title="KMS Initialization and Cleanup">the section called “KMS Initialization and Cleanup”</a>. 175 </p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123849172"></a>Encoders (struct <span class="structname">drm_encoder</span>)</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect3"><a href="drm-kms-init.html#idp1123850308">Encoder Initialization</a></span></dt><dt><span class="sect3"><a href="drm-kms-init.html#idp1123855404">Encoder Operations</a></span></dt></dl></div><p> 176 An encoder takes pixel data from a CRTC and converts it to a format 177 suitable for any attached connectors. On some devices, it may be 178 possible to have a CRTC send data to more than one encoder. In that 179 case, both encoders would receive data from the same scanout buffer, 180 resulting in a "cloned" display configuration across the connectors 181 attached to each encoder. 182 </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123850308"></a>Encoder Initialization</h4></div></div></div><p> 183 As for CRTCs, a KMS driver must create, initialize and register at 184 least one struct <span class="structname">drm_encoder</span> instance. The 185 instance is allocated and zeroed by the driver, possibly as part of a 186 larger structure. 187 </p><p> 188 Drivers must initialize the struct <span class="structname">drm_encoder</span> 189 <em class="structfield"><code>possible_crtcs</code></em> and 190 <em class="structfield"><code>possible_clones</code></em> fields before registering the 191 encoder. Both fields are bitmasks of respectively the CRTCs that the 192 encoder can be connected to, and sibling encoders candidate for cloning. 193 </p><p> 194 After being initialized, the encoder must be registered with a call to 195 <code class="function">drm_encoder_init</code>. The function takes a pointer to 196 the encoder functions and an encoder type. Supported types are 197 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 198 DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A 199 </li><li class="listitem"> 200 DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort 201 </li><li class="listitem"> 202 DRM_MODE_ENCODER_LVDS for display panels 203 </li><li class="listitem"> 204 DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, 205 SCART) 206 </li><li class="listitem"> 207 DRM_MODE_ENCODER_VIRTUAL for virtual machine displays 208 </li></ul></div><p> 209 </p><p> 210 Encoders must be attached to a CRTC to be used. DRM drivers leave 211 encoders unattached at initialization time. Applications (or the fbdev 212 compatibility layer when implemented) are responsible for attaching the 213 encoders they want to use to a CRTC. 214 </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123855404"></a>Encoder Operations</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">void (*destroy)(struct drm_encoder *encoder);</pre><p> 215 Called to destroy the encoder when not needed anymore. See 216 <a class="xref" href="drm-kms-init.html" title="KMS Initialization and Cleanup">the section called “KMS Initialization and Cleanup”</a>. 217 </p></li><li class="listitem"><pre class="synopsis">void (*set_property)(struct drm_plane *plane, 218 struct drm_property *property, uint64_t value);</pre><p> 219 Set the value of the given plane property to 220 <em class="parameter"><code>value</code></em>. See <a class="xref" href="drm-kms-properties.html" title="KMS Properties">the section called “KMS Properties”</a> 221 for more information about properties. 222 </p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123859012"></a>Connectors (struct <span class="structname">drm_connector</span>)</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect3"><a href="drm-kms-init.html#idp1123860500">Connector Initialization</a></span></dt><dt><span class="sect3"><a href="drm-kms-init.html#idp1123877156">Connector Operations</a></span></dt></dl></div><p> 223 A connector is the final destination for pixel data on a device, and 224 usually connects directly to an external display device like a monitor 225 or laptop panel. A connector can only be attached to one encoder at a 226 time. The connector is also the structure where information about the 227 attached display is kept, so it contains fields for display data, EDID 228 data, DPMS & connection status, and information about modes 229 supported on the attached displays. 230 </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123860500"></a>Connector Initialization</h4></div></div></div><p> 231 Finally a KMS driver must create, initialize, register and attach at 232 least one struct <span class="structname">drm_connector</span> instance. The 233 instance is created as other KMS objects and initialized by setting the 234 following fields. 235 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="structfield"><code>interlace_allowed</code></em></span></dt><dd><p> 236 Whether the connector can handle interlaced modes. 237 </p></dd><dt><span class="term"><em class="structfield"><code>doublescan_allowed</code></em></span></dt><dd><p> 238 Whether the connector can handle doublescan. 239 </p></dd><dt><span class="term"><em class="structfield"><code>display_info 240 </code></em></span></dt><dd><p> 241 Display information is filled from EDID information when a display 242 is detected. For non hot-pluggable displays such as flat panels in 243 embedded systems, the driver should initialize the 244 <em class="structfield"><code>display_info</code></em>.<em class="structfield"><code>width_mm</code></em> 245 and 246 <em class="structfield"><code>display_info</code></em>.<em class="structfield"><code>height_mm</code></em> 247 fields with the physical size of the display. 248 </p></dd><dt><span class="term"><a name="drm-kms-connector-polled"></a><em class="structfield"><code>polled</code></em></span></dt><dd><p> 249 Connector polling mode, a combination of 250 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">DRM_CONNECTOR_POLL_HPD</span></dt><dd><p> 251 The connector generates hotplug events and doesn't need to be 252 periodically polled. The CONNECT and DISCONNECT flags must not 253 be set together with the HPD flag. 254 </p></dd><dt><span class="term">DRM_CONNECTOR_POLL_CONNECT</span></dt><dd><p> 255 Periodically poll the connector for connection. 256 </p></dd><dt><span class="term">DRM_CONNECTOR_POLL_DISCONNECT</span></dt><dd><p> 257 Periodically poll the connector for disconnection. 258 </p></dd></dl></div><p> 259 Set to 0 for connectors that don't support connection status 260 discovery. 261 </p></dd></dl></div><p> 262 The connector is then registered with a call to 263 <code class="function">drm_connector_init</code> with a pointer to the connector 264 functions and a connector type, and exposed through sysfs with a call to 265 <code class="function">drm_connector_register</code>. 266 </p><p> 267 Supported connector types are 268 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">DRM_MODE_CONNECTOR_VGA</li><li class="listitem">DRM_MODE_CONNECTOR_DVII</li><li class="listitem">DRM_MODE_CONNECTOR_DVID</li><li class="listitem">DRM_MODE_CONNECTOR_DVIA</li><li class="listitem">DRM_MODE_CONNECTOR_Composite</li><li class="listitem">DRM_MODE_CONNECTOR_SVIDEO</li><li class="listitem">DRM_MODE_CONNECTOR_LVDS</li><li class="listitem">DRM_MODE_CONNECTOR_Component</li><li class="listitem">DRM_MODE_CONNECTOR_9PinDIN</li><li class="listitem">DRM_MODE_CONNECTOR_DisplayPort</li><li class="listitem">DRM_MODE_CONNECTOR_HDMIA</li><li class="listitem">DRM_MODE_CONNECTOR_HDMIB</li><li class="listitem">DRM_MODE_CONNECTOR_TV</li><li class="listitem">DRM_MODE_CONNECTOR_eDP</li><li class="listitem">DRM_MODE_CONNECTOR_VIRTUAL</li></ul></div><p> 269 </p><p> 270 Connectors must be attached to an encoder to be used. For devices that 271 map connectors to encoders 1:1, the connector should be attached at 272 initialization time with a call to 273 <code class="function">drm_mode_connector_attach_encoder</code>. The driver must 274 also set the <span class="structname">drm_connector</span> 275 <em class="structfield"><code>encoder</code></em> field to point to the attached 276 encoder. 277 </p><p> 278 Finally, drivers must initialize the connectors state change detection 279 with a call to <code class="function">drm_kms_helper_poll_init</code>. If at 280 least one connector is pollable but can't generate hotplug interrupts 281 (indicated by the DRM_CONNECTOR_POLL_CONNECT and 282 DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will 283 automatically be queued to periodically poll for changes. Connectors 284 that can generate hotplug interrupts must be marked with the 285 DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must 286 call <code class="function">drm_helper_hpd_irq_event</code>. The function will 287 queue a delayed work to check the state of all connectors, but no 288 periodic polling will be done. 289 </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp1123877156"></a>Connector Operations</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 290 Unless otherwise state, all operations are mandatory. 291 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123877844"></a>DPMS</h5></div></div></div><pre class="synopsis">void (*dpms)(struct drm_connector *connector, int mode);</pre><p> 292 The DPMS operation sets the power state of a connector. The mode 293 argument is one of 294 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>DRM_MODE_DPMS_ON</p></li><li class="listitem"><p>DRM_MODE_DPMS_STANDBY</p></li><li class="listitem"><p>DRM_MODE_DPMS_SUSPEND</p></li><li class="listitem"><p>DRM_MODE_DPMS_OFF</p></li></ul></div><p> 295 </p><p> 296 In all but DPMS_ON mode the encoder to which the connector is attached 297 should put the display in low-power mode by driving its signals 298 appropriately. If more than one connector is attached to the encoder 299 care should be taken not to change the power state of other displays as 300 a side effect. Low-power mode should be propagated to the encoders and 301 CRTCs when all related connectors are put in low-power mode. 302 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123880980"></a>Modes</h5></div></div></div><pre class="synopsis">int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, 303 uint32_t max_height);</pre><p> 304 Fill the mode list with all supported modes for the connector. If the 305 <em class="parameter"><code>max_width</code></em> and <em class="parameter"><code>max_height</code></em> 306 arguments are non-zero, the implementation must ignore all modes wider 307 than <em class="parameter"><code>max_width</code></em> or higher than 308 <em class="parameter"><code>max_height</code></em>. 309 </p><p> 310 The connector must also fill in this operation its 311 <em class="structfield"><code>display_info</code></em> 312 <em class="structfield"><code>width_mm</code></em> and 313 <em class="structfield"><code>height_mm</code></em> fields with the connected display 314 physical size in millimeters. The fields should be set to 0 if the value 315 isn't known or is not applicable (for instance for projector devices). 316 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123884860"></a>Connection Status</h5></div></div></div><p> 317 The connection status is updated through polling or hotplug events when 318 supported (see <a class="xref" href="drm-kms-init.html#drm-kms-connector-polled"><em class="structfield"><code>polled</code></em></a>). The status 319 value is reported to userspace through ioctls and must not be used 320 inside the driver, as it only gets initialized by a call to 321 <code class="function">drm_mode_getconnector</code> from userspace. 322 </p><pre class="synopsis">enum drm_connector_status (*detect)(struct drm_connector *connector, 323 bool force);</pre><p> 324 Check to see if anything is attached to the connector. The 325 <em class="parameter"><code>force</code></em> parameter is set to false whilst polling or 326 to true when checking the connector due to user request. 327 <em class="parameter"><code>force</code></em> can be used by the driver to avoid 328 expensive, destructive operations during automated probing. 329 </p><p> 330 Return connector_status_connected if something is connected to the 331 connector, connector_status_disconnected if nothing is connected and 332 connector_status_unknown if the connection state isn't known. 333 </p><p> 334 Drivers should only return connector_status_connected if the connection 335 status has really been probed as connected. Connectors that can't detect 336 the connection status, or failed connection status probes, should return 337 connector_status_unknown. 338 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp1123889196"></a>Miscellaneous</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">void (*set_property)(struct drm_connector *connector, 339 struct drm_property *property, uint64_t value);</pre><p> 340 Set the value of the given connector property to 341 <em class="parameter"><code>value</code></em>. See <a class="xref" href="drm-kms-properties.html" title="KMS Properties">the section called “KMS Properties”</a> 342 for more information about properties. 343 </p></li><li class="listitem"><pre class="synopsis">void (*destroy)(struct drm_connector *connector);</pre><p> 344 Destroy the connector when not needed anymore. See 345 <a class="xref" href="drm-kms-init.html" title="KMS Initialization and Cleanup">the section called “KMS Initialization and Cleanup”</a>. 346 </p></li></ul></div></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123892868"></a>Cleanup</h3></div></div></div><p> 347 The DRM core manages its objects' lifetime. When an object is not needed 348 anymore the core calls its destroy function, which must clean up and 349 free every resource allocated for the object. Every 350 <code class="function">drm_*_init</code> call must be matched with a 351 corresponding <code class="function">drm_*_cleanup</code> call to cleanup CRTCs 352 (<code class="function">drm_crtc_cleanup</code>), planes 353 (<code class="function">drm_plane_cleanup</code>), encoders 354 (<code class="function">drm_encoder_cleanup</code>) and connectors 355 (<code class="function">drm_connector_cleanup</code>). Furthermore, connectors 356 that have been added to sysfs must be removed by a call to 357 <code class="function">drm_connector_unregister</code> before calling 358 <code class="function">drm_connector_cleanup</code>. 359 </p><p> 360 Connectors state change detection must be cleanup up with a call to 361 <code class="function">drm_kms_helper_poll_fini</code>. 362 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123897460"></a>Output discovery and initialization example</h3></div></div></div><pre class="programlisting"> 363void intel_crt_init(struct drm_device *dev) 364{ 365 struct drm_connector *connector; 366 struct intel_output *intel_output; 367 368 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); 369 if (!intel_output) 370 return; 371 372 connector = &intel_output->base; 373 drm_connector_init(dev, &intel_output->base, 374 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); 375 376 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, 377 DRM_MODE_ENCODER_DAC); 378 379 drm_mode_connector_attach_encoder(&intel_output->base, 380 &intel_output->enc); 381 382 /* Set up the DDC bus. */ 383 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); 384 if (!intel_output->ddc_bus) { 385 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " 386 "failed.\n"); 387 return; 388 } 389 390 intel_output->type = INTEL_OUTPUT_ANALOG; 391 connector->interlace_allowed = 0; 392 connector->doublescan_allowed = 0; 393 394 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); 395 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 396 397 drm_connector_register(connector); 398}</pre><p> 399 In the example above (taken from the i915 driver), a CRTC, connector and 400 encoder combination is created. A device-specific i2c bus is also 401 created for fetching EDID data and performing monitor detection. Once 402 the process is complete, the new connector is registered with sysfs to 403 make its properties available to applications. 404 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123898740"></a>KMS API Functions</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-drm-get-connector-status-name.html"><span class="phrase">drm_get_connector_status_name</span></a></span><span class="refpurpose"> — 405 return a string for connector status 406 </span></dt><dt><span class="refentrytitle"><a href="API-drm-get-subpixel-order-name.html"><span class="phrase">drm_get_subpixel_order_name</span></a></span><span class="refpurpose"> — 407 return a string for a given subpixel enum 408 </span></dt><dt><span class="refentrytitle"><a href="API-drm-get-format-name.html"><span class="phrase">drm_get_format_name</span></a></span><span class="refpurpose"> — 409 return a string for drm fourcc format 410 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-object-find.html"><span class="phrase">drm_mode_object_find</span></a></span><span class="refpurpose"> — 411 look up a drm object with static lifetime 412 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-init.html"><span class="phrase">drm_framebuffer_init</span></a></span><span class="refpurpose"> — 413 initialize a framebuffer 414 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-lookup.html"><span class="phrase">drm_framebuffer_lookup</span></a></span><span class="refpurpose"> — 415 look up a drm framebuffer and grab a reference 416 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-unreference.html"><span class="phrase">drm_framebuffer_unreference</span></a></span><span class="refpurpose"> — 417 unref a framebuffer 418 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-reference.html"><span class="phrase">drm_framebuffer_reference</span></a></span><span class="refpurpose"> — 419 incr the fb refcnt 420 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-unregister-private.html"><span class="phrase">drm_framebuffer_unregister_private</span></a></span><span class="refpurpose"> — 421 unregister a private fb from the lookup idr 422 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-cleanup.html"><span class="phrase">drm_framebuffer_cleanup</span></a></span><span class="refpurpose"> — 423 remove a framebuffer object 424 </span></dt><dt><span class="refentrytitle"><a href="API-drm-framebuffer-remove.html"><span class="phrase">drm_framebuffer_remove</span></a></span><span class="refpurpose"> — 425 remove and unreference a framebuffer object 426 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-init-with-planes.html"><span class="phrase">drm_crtc_init_with_planes</span></a></span><span class="refpurpose"> — 427 Initialise a new CRTC object with specified primary and cursor planes. 428 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-cleanup.html"><span class="phrase">drm_crtc_cleanup</span></a></span><span class="refpurpose"> — 429 Clean up the core crtc usage 430 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-index.html"><span class="phrase">drm_crtc_index</span></a></span><span class="refpurpose"> — 431 find the index of a registered CRTC 432 </span></dt><dt><span class="refentrytitle"><a href="API-drm-display-info-set-bus-formats.html"><span class="phrase">drm_display_info_set_bus_formats</span></a></span><span class="refpurpose"> — 433 set the supported bus formats 434 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-init.html"><span class="phrase">drm_connector_init</span></a></span><span class="refpurpose"> — 435 Init a preallocated connector 436 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-cleanup.html"><span class="phrase">drm_connector_cleanup</span></a></span><span class="refpurpose"> — 437 cleans up an initialised connector 438 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-index.html"><span class="phrase">drm_connector_index</span></a></span><span class="refpurpose"> — 439 find the index of a registered connector 440 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-register.html"><span class="phrase">drm_connector_register</span></a></span><span class="refpurpose"> — 441 register a connector 442 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-unregister.html"><span class="phrase">drm_connector_unregister</span></a></span><span class="refpurpose"> — 443 unregister a connector 444 </span></dt><dt><span class="refentrytitle"><a href="API-drm-connector-unplug-all.html"><span class="phrase">drm_connector_unplug_all</span></a></span><span class="refpurpose"> — 445 unregister connector userspace interfaces 446 </span></dt><dt><span class="refentrytitle"><a href="API-drm-encoder-init.html"><span class="phrase">drm_encoder_init</span></a></span><span class="refpurpose"> — 447 Init a preallocated encoder 448 </span></dt><dt><span class="refentrytitle"><a href="API-drm-encoder-cleanup.html"><span class="phrase">drm_encoder_cleanup</span></a></span><span class="refpurpose"> — 449 cleans up an initialised encoder 450 </span></dt><dt><span class="refentrytitle"><a href="API-drm-universal-plane-init.html"><span class="phrase">drm_universal_plane_init</span></a></span><span class="refpurpose"> — 451 Initialize a new universal plane object 452 </span></dt><dt><span class="refentrytitle"><a href="API-drm-plane-init.html"><span class="phrase">drm_plane_init</span></a></span><span class="refpurpose"> — 453 Initialize a legacy plane 454 </span></dt><dt><span class="refentrytitle"><a href="API-drm-plane-cleanup.html"><span class="phrase">drm_plane_cleanup</span></a></span><span class="refpurpose"> — 455 Clean up the core plane usage 456 </span></dt><dt><span class="refentrytitle"><a href="API-drm-plane-index.html"><span class="phrase">drm_plane_index</span></a></span><span class="refpurpose"> — 457 find the index of a registered plane 458 </span></dt><dt><span class="refentrytitle"><a href="API-drm-plane-force-disable.html"><span class="phrase">drm_plane_force_disable</span></a></span><span class="refpurpose"> — 459 Forcibly disable a plane 460 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-dvi-i-properties.html"><span class="phrase">drm_mode_create_dvi_i_properties</span></a></span><span class="refpurpose"> — 461 create DVI-I specific connector properties 462 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-tv-properties.html"><span class="phrase">drm_mode_create_tv_properties</span></a></span><span class="refpurpose"> — 463 create TV specific connector properties 464 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-scaling-mode-property.html"><span class="phrase">drm_mode_create_scaling_mode_property</span></a></span><span class="refpurpose"> — 465 create scaling mode property 466 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-aspect-ratio-property.html"><span class="phrase">drm_mode_create_aspect_ratio_property</span></a></span><span class="refpurpose"> — 467 create aspect ratio property 468 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-dirty-info-property.html"><span class="phrase">drm_mode_create_dirty_info_property</span></a></span><span class="refpurpose"> — 469 create dirty property 470 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-suggested-offset-properties.html"><span class="phrase">drm_mode_create_suggested_offset_properties</span></a></span><span class="refpurpose"> — 471 create suggests offset properties 472 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-set-config-internal.html"><span class="phrase">drm_mode_set_config_internal</span></a></span><span class="refpurpose"> — 473 helper to call ->set_config 474 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-get-hv-timing.html"><span class="phrase">drm_crtc_get_hv_timing</span></a></span><span class="refpurpose"> — 475 Fetches hdisplay/vdisplay for given mode 476 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-check-viewport.html"><span class="phrase">drm_crtc_check_viewport</span></a></span><span class="refpurpose"> — 477 Checks that a framebuffer is big enough for the CRTC viewport 478 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-legacy-fb-format.html"><span class="phrase">drm_mode_legacy_fb_format</span></a></span><span class="refpurpose"> — 479 compute drm fourcc code from legacy description 480 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create.html"><span class="phrase">drm_property_create</span></a></span><span class="refpurpose"> — 481 create a new property type 482 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-enum.html"><span class="phrase">drm_property_create_enum</span></a></span><span class="refpurpose"> — 483 create a new enumeration property type 484 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-bitmask.html"><span class="phrase">drm_property_create_bitmask</span></a></span><span class="refpurpose"> — 485 create a new bitmask property type 486 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-range.html"><span class="phrase">drm_property_create_range</span></a></span><span class="refpurpose"> — 487 create a new unsigned ranged property type 488 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-signed-range.html"><span class="phrase">drm_property_create_signed_range</span></a></span><span class="refpurpose"> — 489 create a new signed ranged property type 490 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-object.html"><span class="phrase">drm_property_create_object</span></a></span><span class="refpurpose"> — 491 create a new object property type 492 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-create-bool.html"><span class="phrase">drm_property_create_bool</span></a></span><span class="refpurpose"> — 493 create a new boolean property type 494 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-add-enum.html"><span class="phrase">drm_property_add_enum</span></a></span><span class="refpurpose"> — 495 add a possible value to an enumeration property 496 </span></dt><dt><span class="refentrytitle"><a href="API-drm-property-destroy.html"><span class="phrase">drm_property_destroy</span></a></span><span class="refpurpose"> — 497 destroy a drm property 498 </span></dt><dt><span class="refentrytitle"><a href="API-drm-object-attach-property.html"><span class="phrase">drm_object_attach_property</span></a></span><span class="refpurpose"> — 499 attach a property to a modeset object 500 </span></dt><dt><span class="refentrytitle"><a href="API-drm-object-property-set-value.html"><span class="phrase">drm_object_property_set_value</span></a></span><span class="refpurpose"> — 501 set the value of a property 502 </span></dt><dt><span class="refentrytitle"><a href="API-drm-object-property-get-value.html"><span class="phrase">drm_object_property_get_value</span></a></span><span class="refpurpose"> — 503 retrieve the value of a property 504 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-connector-set-path-property.html"><span class="phrase">drm_mode_connector_set_path_property</span></a></span><span class="refpurpose"> — 505 set tile property on connector 506 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-connector-set-tile-property.html"><span class="phrase">drm_mode_connector_set_tile_property</span></a></span><span class="refpurpose"> — 507 set tile property on connector 508 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-connector-update-edid-property.html"><span class="phrase">drm_mode_connector_update_edid_property</span></a></span><span class="refpurpose"> — 509 update the edid property of a connector 510 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-plane-set-obj-prop.html"><span class="phrase">drm_mode_plane_set_obj_prop</span></a></span><span class="refpurpose"> — 511 set the value of a property 512 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-connector-attach-encoder.html"><span class="phrase">drm_mode_connector_attach_encoder</span></a></span><span class="refpurpose"> — 513 attach a connector to an encoder 514 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-crtc-set-gamma-size.html"><span class="phrase">drm_mode_crtc_set_gamma_size</span></a></span><span class="refpurpose"> — 515 set the gamma table size 516 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-config-reset.html"><span class="phrase">drm_mode_config_reset</span></a></span><span class="refpurpose"> — 517 call ->reset callbacks 518 </span></dt><dt><span class="refentrytitle"><a href="API-drm-fb-get-bpp-depth.html"><span class="phrase">drm_fb_get_bpp_depth</span></a></span><span class="refpurpose"> — 519 get the bpp/depth values for format 520 </span></dt><dt><span class="refentrytitle"><a href="API-drm-format-num-planes.html"><span class="phrase">drm_format_num_planes</span></a></span><span class="refpurpose"> — 521 get the number of planes for format 522 </span></dt><dt><span class="refentrytitle"><a href="API-drm-format-plane-cpp.html"><span class="phrase">drm_format_plane_cpp</span></a></span><span class="refpurpose"> — 523 determine the bytes per pixel value 524 </span></dt><dt><span class="refentrytitle"><a href="API-drm-format-horz-chroma-subsampling.html"><span class="phrase">drm_format_horz_chroma_subsampling</span></a></span><span class="refpurpose"> — 525 get the horizontal chroma subsampling factor 526 </span></dt><dt><span class="refentrytitle"><a href="API-drm-format-vert-chroma-subsampling.html"><span class="phrase">drm_format_vert_chroma_subsampling</span></a></span><span class="refpurpose"> — 527 get the vertical chroma subsampling factor 528 </span></dt><dt><span class="refentrytitle"><a href="API-drm-rotation-simplify.html"><span class="phrase">drm_rotation_simplify</span></a></span><span class="refpurpose"> — 529 Try to simplify the rotation 530 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-config-init.html"><span class="phrase">drm_mode_config_init</span></a></span><span class="refpurpose"> — 531 initialize DRM mode_configuration structure 532 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-config-cleanup.html"><span class="phrase">drm_mode_config_cleanup</span></a></span><span class="refpurpose"> — 533 free up DRM mode_config info 534 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-get-tile-group.html"><span class="phrase">drm_mode_get_tile_group</span></a></span><span class="refpurpose"> — 535 get a reference to an existing tile group 536 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-tile-group.html"><span class="phrase">drm_mode_create_tile_group</span></a></span><span class="refpurpose"> — 537 create a tile group from a displayid description 538 </span></dt></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1124538092"></a>KMS Data Structures</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-struct-drm-crtc-state.html"><span class="phrase">struct drm_crtc_state</span></a></span><span class="refpurpose"> — 539 mutable CRTC state 540 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-crtc-funcs.html"><span class="phrase">struct drm_crtc_funcs</span></a></span><span class="refpurpose"> — 541 control CRTCs for a given device 542 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-crtc.html"><span class="phrase">struct drm_crtc</span></a></span><span class="refpurpose"> — 543 central CRTC control structure 544 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-connector-state.html"><span class="phrase">struct drm_connector_state</span></a></span><span class="refpurpose"> — 545 mutable connector state 546 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-connector-funcs.html"><span class="phrase">struct drm_connector_funcs</span></a></span><span class="refpurpose"> — 547 control connectors on a given device 548 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-encoder-funcs.html"><span class="phrase">struct drm_encoder_funcs</span></a></span><span class="refpurpose"> — 549 encoder controls 550 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-encoder.html"><span class="phrase">struct drm_encoder</span></a></span><span class="refpurpose"> — 551 central DRM encoder structure 552 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-connector.html"><span class="phrase">struct drm_connector</span></a></span><span class="refpurpose"> — 553 central DRM connector control structure 554 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-plane-state.html"><span class="phrase">struct drm_plane_state</span></a></span><span class="refpurpose"> — 555 mutable plane state 556 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-plane-funcs.html"><span class="phrase">struct drm_plane_funcs</span></a></span><span class="refpurpose"> — 557 driver plane control functions 558 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-plane.html"><span class="phrase">struct drm_plane</span></a></span><span class="refpurpose"> — 559 central DRM plane control structure 560 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-bridge-funcs.html"><span class="phrase">struct drm_bridge_funcs</span></a></span><span class="refpurpose"> — 561 drm_bridge control functions 562 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-bridge.html"><span class="phrase">struct drm_bridge</span></a></span><span class="refpurpose"> — 563 central DRM bridge control structure 564 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-atomic-state.html"><span class="phrase">struct drm_atomic_state</span></a></span><span class="refpurpose"> — 565 the global state object for atomic updates 566 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-mode-set.html"><span class="phrase">struct drm_mode_set</span></a></span><span class="refpurpose"> — 567 new values for a CRTC config change 568 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-mode-config-funcs.html"><span class="phrase">struct drm_mode_config_funcs</span></a></span><span class="refpurpose"> — 569 basic driver provided mode setting functions 570 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-mode-group.html"><span class="phrase">struct drm_mode_group</span></a></span><span class="refpurpose"> — 571 group of mode setting resources for potential sub-grouping 572 </span></dt><dt><span class="refentrytitle"><a href="API-struct-drm-mode-config.html"><span class="phrase">struct drm_mode_config</span></a></span><span class="refpurpose"> — 573 Mode configuration control structure 574 </span></dt><dt><span class="refentrytitle"><a href="API-drm-for-each-plane-mask.html"><span class="phrase">drm_for_each_plane_mask</span></a></span><span class="refpurpose"> — 575 iterate over planes specified by bitmask 576 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-mask.html"><span class="phrase">drm_crtc_mask</span></a></span><span class="refpurpose"> — 577 find the mask of a registered CRTC 578 </span></dt><dt><span class="refentrytitle"><a href="API-drm-encoder-crtc-ok.html"><span class="phrase">drm_encoder_crtc_ok</span></a></span><span class="refpurpose"> — 579 can a given crtc drive a given encoder? 580 </span></dt></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1124843020"></a>KMS Locking</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-struct-drm-modeset-acquire-ctx.html"><span class="phrase">struct drm_modeset_acquire_ctx</span></a></span><span class="refpurpose"> — 581 locking context (see ww_acquire_ctx) 582 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock-init.html"><span class="phrase">drm_modeset_lock_init</span></a></span><span class="refpurpose"> — 583 initialize lock 584 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock-fini.html"><span class="phrase">drm_modeset_lock_fini</span></a></span><span class="refpurpose"> — 585 cleanup lock 586 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-is-locked.html"><span class="phrase">drm_modeset_is_locked</span></a></span><span class="refpurpose"> — 587 equivalent to <code class="function">mutex_is_locked</code> 588 </span></dt><dt><span class="refentrytitle"><a href="API---drm-modeset-lock-all.html"><span class="phrase">__drm_modeset_lock_all</span></a></span><span class="refpurpose"> — 589 internal helper to grab all modeset locks 590 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock-all.html"><span class="phrase">drm_modeset_lock_all</span></a></span><span class="refpurpose"> — 591 take all modeset locks 592 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-unlock-all.html"><span class="phrase">drm_modeset_unlock_all</span></a></span><span class="refpurpose"> — 593 drop all modeset locks 594 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock-crtc.html"><span class="phrase">drm_modeset_lock_crtc</span></a></span><span class="refpurpose"> — 595 lock crtc with hidden acquire ctx for a plane update 596 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-legacy-acquire-ctx.html"><span class="phrase">drm_modeset_legacy_acquire_ctx</span></a></span><span class="refpurpose"> — 597 find acquire ctx for legacy ioctls 598 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-unlock-crtc.html"><span class="phrase">drm_modeset_unlock_crtc</span></a></span><span class="refpurpose"> — 599 drop crtc lock 600 </span></dt><dt><span class="refentrytitle"><a href="API-drm-warn-on-modeset-not-all-locked.html"><span class="phrase">drm_warn_on_modeset_not_all_locked</span></a></span><span class="refpurpose"> — 601 check that all modeset locks are locked 602 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-acquire-init.html"><span class="phrase">drm_modeset_acquire_init</span></a></span><span class="refpurpose"> — 603 initialize acquire context 604 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-acquire-fini.html"><span class="phrase">drm_modeset_acquire_fini</span></a></span><span class="refpurpose"> — 605 cleanup acquire context 606 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-drop-locks.html"><span class="phrase">drm_modeset_drop_locks</span></a></span><span class="refpurpose"> — 607 drop all locks 608 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-backoff.html"><span class="phrase">drm_modeset_backoff</span></a></span><span class="refpurpose"> — 609 deadlock avoidance backoff 610 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-backoff-interruptible.html"><span class="phrase">drm_modeset_backoff_interruptible</span></a></span><span class="refpurpose"> — 611 deadlock avoidance backoff 612 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock.html"><span class="phrase">drm_modeset_lock</span></a></span><span class="refpurpose"> — 613 take modeset lock 614 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-lock-interruptible.html"><span class="phrase">drm_modeset_lock_interruptible</span></a></span><span class="refpurpose"> — 615 take modeset lock 616 </span></dt><dt><span class="refentrytitle"><a href="API-drm-modeset-unlock.html"><span class="phrase">drm_modeset_unlock</span></a></span><span class="refpurpose"> — 617 drop modeset lock 618 </span></dt></dl></div><p> 619 </p><p> 620 As KMS moves toward more fine grained locking, and atomic ioctl where 621 userspace can indirectly control locking order, it becomes necessary 622 to use ww_mutex and acquire-contexts to avoid deadlocks. But because 623 the locking is more distributed around the driver code, we want a bit 624 of extra utility/tracking out of our acquire-ctx. This is provided 625 by drm_modeset_lock / drm_modeset_acquire_ctx. 626 </p><p> 627 For basic principles of ww_mutex, see: Documentation/locking/ww-mutex-design.txt 628 </p><p> 629 The basic usage pattern is to: 630 </p><p> 631 drm_modeset_acquire_init(<span class="structname">ctx</span>) 632 retry: 633 foreach (lock in random_ordered_set_of_locks) { 634 ret = drm_modeset_lock(lock, <span class="structname">ctx</span>) 635 if (ret == -EDEADLK) { 636 drm_modeset_backoff(<span class="structname">ctx</span>); 637 goto retry; 638 } 639 } 640 </p><p> 641 ... do stuff ... 642 </p><p> 643 drm_modeset_drop_locks(<span class="structname">ctx</span>); 644 drm_modeset_acquire_fini(<span class="structname">ctx</span>); 645</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-drm-atomic-async-commit.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="drmInternals.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-drm-get-connector-status-name.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">drm_atomic_async_commit</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">drm_get_connector_status_name</span></td></tr></table></div></body></html> 646