1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Mode Setting</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-struct-drm-gem-cma-object.html" title="struct drm_gem_cma_object"><link rel="next" href="API-drm-mode-is-stereo.html" title="drm_mode_is_stereo"></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">Mode Setting</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-struct-drm-gem-cma-object.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-mode-is-stereo.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-mode-setting"></a>Mode Setting</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123353068">Display Modes Function Reference</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123612996">Atomic Mode Setting Function Reference</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123785660">Frame Buffer Creation</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123799668">Dumb Buffer Objects</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123808604">Output Polling</a></span></dt><dt><span class="sect2"><a href="drm-mode-setting.html#idp1123810164">Locking</a></span></dt></dl></div><p> 2 Drivers must initialize the mode setting core by calling 3 <code class="function">drm_mode_config_init</code> on the DRM device. The function 4 initializes the <span class="structname">drm_device</span> 5 <em class="structfield"><code>mode_config</code></em> field and never fails. Once done, 6 mode configuration must be setup by initializing the following fields. 7 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">int min_width, min_height; 8int max_width, max_height;</pre><p> 9 Minimum and maximum width and height of the frame buffers in pixel 10 units. 11 </p></li><li class="listitem"><pre class="synopsis">struct drm_mode_config_funcs *funcs;</pre><p>Mode setting functions.</p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123353068"></a>Display Modes Function Reference</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-drm-mode-is-stereo.html"><span class="phrase">drm_mode_is_stereo</span></a></span><span class="refpurpose"> — 12 check for stereo mode flags 13 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-debug-printmodeline.html"><span class="phrase">drm_mode_debug_printmodeline</span></a></span><span class="refpurpose"> — 14 print a mode to dmesg 15 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create.html"><span class="phrase">drm_mode_create</span></a></span><span class="refpurpose"> — 16 create a new display mode 17 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-destroy.html"><span class="phrase">drm_mode_destroy</span></a></span><span class="refpurpose"> — 18 remove a mode 19 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-probed-add.html"><span class="phrase">drm_mode_probed_add</span></a></span><span class="refpurpose"> — 20 add a mode to a connector's probed_mode list 21 </span></dt><dt><span class="refentrytitle"><a href="API-drm-cvt-mode.html"><span class="phrase">drm_cvt_mode</span></a></span><span class="refpurpose"> — 22 create a modeline based on the CVT algorithm 23 </span></dt><dt><span class="refentrytitle"><a href="API-drm-gtf-mode-complex.html"><span class="phrase">drm_gtf_mode_complex</span></a></span><span class="refpurpose"> — 24 create the modeline based on the full GTF algorithm 25 </span></dt><dt><span class="refentrytitle"><a href="API-drm-gtf-mode.html"><span class="phrase">drm_gtf_mode</span></a></span><span class="refpurpose"> — 26 create the modeline based on the GTF algorithm 27 </span></dt><dt><span class="refentrytitle"><a href="API-drm-display-mode-from-videomode.html"><span class="phrase">drm_display_mode_from_videomode</span></a></span><span class="refpurpose"> — 28 fill in <em class="parameter"><code>dmode</code></em> using <em class="parameter"><code>vm</code></em>, 29 </span></dt><dt><span class="refentrytitle"><a href="API-drm-display-mode-to-videomode.html"><span class="phrase">drm_display_mode_to_videomode</span></a></span><span class="refpurpose"> — 30 fill in <em class="parameter"><code>vm</code></em> using <em class="parameter"><code>dmode</code></em>, 31 </span></dt><dt><span class="refentrytitle"><a href="API-of-get-drm-display-mode.html"><span class="phrase">of_get_drm_display_mode</span></a></span><span class="refpurpose"> — 32 get a drm_display_mode from devicetree 33 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-set-name.html"><span class="phrase">drm_mode_set_name</span></a></span><span class="refpurpose"> — 34 set the name on a mode 35 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-vrefresh.html"><span class="phrase">drm_mode_vrefresh</span></a></span><span class="refpurpose"> — 36 get the vrefresh of a mode 37 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-set-crtcinfo.html"><span class="phrase">drm_mode_set_crtcinfo</span></a></span><span class="refpurpose"> — 38 set CRTC modesetting timing parameters 39 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-copy.html"><span class="phrase">drm_mode_copy</span></a></span><span class="refpurpose"> — 40 copy the mode 41 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-duplicate.html"><span class="phrase">drm_mode_duplicate</span></a></span><span class="refpurpose"> — 42 allocate and duplicate an existing mode 43 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-equal.html"><span class="phrase">drm_mode_equal</span></a></span><span class="refpurpose"> — 44 test modes for equality 45 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-equal-no-clocks-no-stereo.html"><span class="phrase">drm_mode_equal_no_clocks_no_stereo</span></a></span><span class="refpurpose"> — 46 test modes for equality 47 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-validate-basic.html"><span class="phrase">drm_mode_validate_basic</span></a></span><span class="refpurpose"> — 48 make sure the mode is somewhat sane 49 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-validate-size.html"><span class="phrase">drm_mode_validate_size</span></a></span><span class="refpurpose"> — 50 make sure modes adhere to size constraints 51 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-prune-invalid.html"><span class="phrase">drm_mode_prune_invalid</span></a></span><span class="refpurpose"> — 52 remove invalid modes from mode list 53 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-sort.html"><span class="phrase">drm_mode_sort</span></a></span><span class="refpurpose"> — 54 sort mode list 55 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-connector-list-update.html"><span class="phrase">drm_mode_connector_list_update</span></a></span><span class="refpurpose"> — 56 update the mode list for the connector 57 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-parse-command-line-for-connector.html"><span class="phrase">drm_mode_parse_command_line_for_connector</span></a></span><span class="refpurpose"> — 58 parse command line modeline for connector 59 </span></dt><dt><span class="refentrytitle"><a href="API-drm-mode-create-from-cmdline-mode.html"><span class="phrase">drm_mode_create_from_cmdline_mode</span></a></span><span class="refpurpose"> — 60 convert a command line modeline into a DRM display mode 61 </span></dt></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123612996"></a>Atomic Mode Setting Function Reference</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-drm-atomic-state-alloc.html"><span class="phrase">drm_atomic_state_alloc</span></a></span><span class="refpurpose"> — 62 allocate atomic state 63 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-state-clear.html"><span class="phrase">drm_atomic_state_clear</span></a></span><span class="refpurpose"> — 64 clear state object 65 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-state-free.html"><span class="phrase">drm_atomic_state_free</span></a></span><span class="refpurpose"> — 66 free all memory for an atomic state 67 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-get-crtc-state.html"><span class="phrase">drm_atomic_get_crtc_state</span></a></span><span class="refpurpose"> — 68 get crtc state 69 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-crtc-set-property.html"><span class="phrase">drm_atomic_crtc_set_property</span></a></span><span class="refpurpose"> — 70 set property on CRTC 71 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-get-plane-state.html"><span class="phrase">drm_atomic_get_plane_state</span></a></span><span class="refpurpose"> — 72 get plane state 73 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-plane-set-property.html"><span class="phrase">drm_atomic_plane_set_property</span></a></span><span class="refpurpose"> — 74 set property on plane 75 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-get-connector-state.html"><span class="phrase">drm_atomic_get_connector_state</span></a></span><span class="refpurpose"> — 76 get connector state 77 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-connector-set-property.html"><span class="phrase">drm_atomic_connector_set_property</span></a></span><span class="refpurpose"> — 78 set property on connector. 79 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-set-crtc-for-plane.html"><span class="phrase">drm_atomic_set_crtc_for_plane</span></a></span><span class="refpurpose"> — 80 set crtc for plane 81 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-set-fb-for-plane.html"><span class="phrase">drm_atomic_set_fb_for_plane</span></a></span><span class="refpurpose"> — 82 set framebuffer for plane 83 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-set-crtc-for-connector.html"><span class="phrase">drm_atomic_set_crtc_for_connector</span></a></span><span class="refpurpose"> — 84 set crtc for connector 85 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-add-affected-connectors.html"><span class="phrase">drm_atomic_add_affected_connectors</span></a></span><span class="refpurpose"> — 86 add connectors for crtc 87 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-connectors-for-crtc.html"><span class="phrase">drm_atomic_connectors_for_crtc</span></a></span><span class="refpurpose"> — 88 count number of connected outputs 89 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-legacy-backoff.html"><span class="phrase">drm_atomic_legacy_backoff</span></a></span><span class="refpurpose"> — 90 locking backoff for legacy ioctls 91 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-check-only.html"><span class="phrase">drm_atomic_check_only</span></a></span><span class="refpurpose"> — 92 check whether a given config would work 93 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-commit.html"><span class="phrase">drm_atomic_commit</span></a></span><span class="refpurpose"> — 94 commit configuration atomically 95 </span></dt><dt><span class="refentrytitle"><a href="API-drm-atomic-async-commit.html"><span class="phrase">drm_atomic_async_commit</span></a></span><span class="refpurpose"> — 96 atomic<span class="structname">async</span> configuration commit 97 </span></dt></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123785660"></a>Frame Buffer Creation</h3></div></div></div><pre class="synopsis">struct drm_framebuffer *(*fb_create)(struct drm_device *dev, 98 struct drm_file *file_priv, 99 struct drm_mode_fb_cmd2 *mode_cmd);</pre><p> 100 Frame buffers are abstract memory objects that provide a source of 101 pixels to scanout to a CRTC. Applications explicitly request the 102 creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and 103 receive an opaque handle that can be passed to the KMS CRTC control, 104 plane configuration and page flip functions. 105 </p><p> 106 Frame buffers rely on the underneath memory manager for low-level memory 107 operations. When creating a frame buffer applications pass a memory 108 handle (or a list of memory handles for multi-planar formats) through 109 the <em class="parameter"><code>drm_mode_fb_cmd2</code></em> argument. For drivers using 110 GEM as their userspace buffer management interface this would be a GEM 111 handle. Drivers are however free to use their own backing storage object 112 handles, e.g. vmwgfx directly exposes special TTM handles to userspace 113 and so expects TTM handles in the create ioctl and not GEM handles. 114 </p><p> 115 Drivers must first validate the requested frame buffer parameters passed 116 through the mode_cmd argument. In particular this is where invalid 117 sizes, pixel formats or pitches can be caught. 118 </p><p> 119 If the parameters are deemed valid, drivers then create, initialize and 120 return an instance of struct <span class="structname">drm_framebuffer</span>. 121 If desired the instance can be embedded in a larger driver-specific 122 structure. Drivers must fill its <em class="structfield"><code>width</code></em>, 123 <em class="structfield"><code>height</code></em>, <em class="structfield"><code>pitches</code></em>, 124 <em class="structfield"><code>offsets</code></em>, <em class="structfield"><code>depth</code></em>, 125 <em class="structfield"><code>bits_per_pixel</code></em> and 126 <em class="structfield"><code>pixel_format</code></em> fields from the values passed 127 through the <em class="parameter"><code>drm_mode_fb_cmd2</code></em> argument. They 128 should call the <code class="function">drm_helper_mode_fill_fb_struct</code> 129 helper function to do so. 130 </p><p> 131 The initialization of the new framebuffer instance is finalized with a 132 call to <code class="function">drm_framebuffer_init</code> which takes a pointer 133 to DRM frame buffer operations (struct 134 <span class="structname">drm_framebuffer_funcs</span>). Note that this function 135 publishes the framebuffer and so from this point on it can be accessed 136 concurrently from other threads. Hence it must be the last step in the 137 driver's framebuffer initialization sequence. Frame buffer operations 138 are 139 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">int (*create_handle)(struct drm_framebuffer *fb, 140 struct drm_file *file_priv, unsigned int *handle);</pre><p> 141 Create a handle to the frame buffer underlying memory object. If 142 the frame buffer uses a multi-plane format, the handle will 143 reference the memory object associated with the first plane. 144 </p><p> 145 Drivers call <code class="function">drm_gem_handle_create</code> to create 146 the handle. 147 </p></li><li class="listitem"><pre class="synopsis">void (*destroy)(struct drm_framebuffer *framebuffer);</pre><p> 148 Destroy the frame buffer object and frees all associated 149 resources. Drivers must call 150 <code class="function">drm_framebuffer_cleanup</code> to free resources 151 allocated by the DRM core for the frame buffer object, and must 152 make sure to unreference all memory objects associated with the 153 frame buffer. Handles created by the 154 <code class="methodname">create_handle</code> operation are released by 155 the DRM core. 156 </p></li><li class="listitem"><pre class="synopsis">int (*dirty)(struct drm_framebuffer *framebuffer, 157 struct drm_file *file_priv, unsigned flags, unsigned color, 158 struct drm_clip_rect *clips, unsigned num_clips);</pre><p> 159 This optional operation notifies the driver that a region of the 160 frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB 161 ioctl call. 162 </p></li></ul></div><p> 163 </p><p> 164 The lifetime of a drm framebuffer is controlled with a reference count, 165 drivers can grab additional references with 166 <code class="function">drm_framebuffer_reference</code>and drop them 167 again with <code class="function">drm_framebuffer_unreference</code>. For 168 driver-private framebuffers for which the last reference is never 169 dropped (e.g. for the fbdev framebuffer when the struct 170 <span class="structname">drm_framebuffer</span> is embedded into the fbdev 171 helper struct) drivers can manually clean up a framebuffer at module 172 unload time with 173 <code class="function">drm_framebuffer_unregister_private</code>. 174 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123799668"></a>Dumb Buffer Objects</h3></div></div></div><p> 175 The KMS API doesn't standardize backing storage object creation and 176 leaves it to driver-specific ioctls. Furthermore actually creating a 177 buffer object even for GEM-based drivers is done through a 178 driver-specific ioctl - GEM only has a common userspace interface for 179 sharing and destroying objects. While not an issue for full-fledged 180 graphics stacks that include device-specific userspace components (in 181 libdrm for instance), this limit makes DRM-based early boot graphics 182 unnecessarily complex. 183 </p><p> 184 Dumb objects partly alleviate the problem by providing a standard 185 API to create dumb buffers suitable for scanout, which can then be used 186 to create KMS frame buffers. 187 </p><p> 188 To support dumb objects drivers must implement the 189 <code class="methodname">dumb_create</code>, 190 <code class="methodname">dumb_destroy</code> and 191 <code class="methodname">dumb_map_offset</code> operations. 192 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, 193 struct drm_mode_create_dumb *args);</pre><p> 194 The <code class="methodname">dumb_create</code> operation creates a driver 195 object (GEM or TTM handle) suitable for scanout based on the 196 width, height and depth from the struct 197 <span class="structname">drm_mode_create_dumb</span> argument. It fills the 198 argument's <em class="structfield"><code>handle</code></em>, 199 <em class="structfield"><code>pitch</code></em> and <em class="structfield"><code>size</code></em> 200 fields with a handle for the newly created object and its line 201 pitch and size in bytes. 202 </p></li><li class="listitem"><pre class="synopsis">int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, 203 uint32_t handle);</pre><p> 204 The <code class="methodname">dumb_destroy</code> operation destroys a dumb 205 object created by <code class="methodname">dumb_create</code>. 206 </p></li><li class="listitem"><pre class="synopsis">int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, 207 uint32_t handle, uint64_t *offset);</pre><p> 208 The <code class="methodname">dumb_map_offset</code> operation associates an 209 mmap fake offset with the object given by the handle and returns 210 it. Drivers must use the 211 <code class="function">drm_gem_create_mmap_offset</code> function to 212 associate the fake offset as described in 213 <a class="xref" href="drm-memory-management.html#drm-gem-objects-mapping" title="GEM Objects Mapping">the section called “GEM Objects Mapping”</a>. 214 </p></li></ul></div><p> 215 Note that dumb objects may not be used for gpu acceleration, as has been 216 attempted on some ARM embedded platforms. Such drivers really must have 217 a hardware-specific ioctl to allocate suitable buffer objects. 218 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123808604"></a>Output Polling</h3></div></div></div><pre class="synopsis">void (*output_poll_changed)(struct drm_device *dev);</pre><p> 219 This operation notifies the driver that the status of one or more 220 connectors has changed. Drivers that use the fb helper can just call the 221 <code class="function">drm_fb_helper_hotplug_event</code> function to handle this 222 operation. 223 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1123810164"></a>Locking</h3></div></div></div><p> 224 Beside some lookup structures with their own locking (which is hidden 225 behind the interface functions) most of the modeset state is protected 226 by the <code class="code">dev-<mode_config.lock</code> mutex and additionally 227 per-crtc locks to allow cursor updates, pageflips and similar operations 228 to occur concurrently with background tasks like output detection. 229 Operations which cross domains like a full modeset always grab all 230 locks. Drivers there need to protect resources shared between crtcs with 231 additional locking. They also need to be careful to always grab the 232 relevant crtc locks if a modset functions touches crtc state, e.g. for 233 load detection (which does only grab the <code class="code">mode_config.lock</code> 234 to allow concurrent screen updates on live crtcs). 235 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-struct-drm-gem-cma-object.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-mode-is-stereo.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">struct drm_gem_cma_object</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_mode_is_stereo</span></td></tr></table></div></body></html> 236