1 ========================= 1 =========================
2 Kernel Mode Setting (KMS) 2 Kernel Mode Setting (KMS)
3 ========================= 3 =========================
4 4
5 Drivers must initialize the mode setting core 5 Drivers must initialize the mode setting core by calling
6 drmm_mode_config_init() on the DRM device. The !! 6 :c:func:`drm_mode_config_init()` on the DRM device. The function
7 initializes the :c:type:`struct drm_device <dr 7 initializes the :c:type:`struct drm_device <drm_device>`
8 mode_config field and never fails. Once done, 8 mode_config field and never fails. Once done, mode configuration must
9 be setup by initializing the following fields. 9 be setup by initializing the following fields.
10 10
11 - int min_width, min_height; int max_width, m 11 - int min_width, min_height; int max_width, max_height;
12 Minimum and maximum width and height of the 12 Minimum and maximum width and height of the frame buffers in pixel
13 units. 13 units.
14 14
15 - struct drm_mode_config_funcs \*funcs; 15 - struct drm_mode_config_funcs \*funcs;
16 Mode setting functions. 16 Mode setting functions.
17 17
18 Overview 18 Overview
19 ======== 19 ========
20 20
21 .. kernel-render:: DOT 21 .. kernel-render:: DOT
22 :alt: KMS Display Pipeline 22 :alt: KMS Display Pipeline
23 :caption: KMS Display Pipeline Overview 23 :caption: KMS Display Pipeline Overview
24 24
25 digraph "KMS" { 25 digraph "KMS" {
26 node [shape=box] 26 node [shape=box]
27 27
28 subgraph cluster_static { 28 subgraph cluster_static {
29 style=dashed 29 style=dashed
30 label="Static Objects" 30 label="Static Objects"
31 31
32 node [bgcolor=grey style=filled] 32 node [bgcolor=grey style=filled]
33 "drm_plane A" -> "drm_crtc" 33 "drm_plane A" -> "drm_crtc"
34 "drm_plane B" -> "drm_crtc" 34 "drm_plane B" -> "drm_crtc"
35 "drm_crtc" -> "drm_encoder A" 35 "drm_crtc" -> "drm_encoder A"
36 "drm_crtc" -> "drm_encoder B" 36 "drm_crtc" -> "drm_encoder B"
37 } 37 }
38 38
39 subgraph cluster_user_created { 39 subgraph cluster_user_created {
40 style=dashed 40 style=dashed
41 label="Userspace-Created" 41 label="Userspace-Created"
42 42
43 node [shape=oval] 43 node [shape=oval]
44 "drm_framebuffer 1" -> "drm_plane A" 44 "drm_framebuffer 1" -> "drm_plane A"
45 "drm_framebuffer 2" -> "drm_plane B" 45 "drm_framebuffer 2" -> "drm_plane B"
46 } 46 }
47 47
48 subgraph cluster_connector { 48 subgraph cluster_connector {
49 style=dashed 49 style=dashed
50 label="Hotpluggable" 50 label="Hotpluggable"
51 51
52 "drm_encoder A" -> "drm_connector A" 52 "drm_encoder A" -> "drm_connector A"
53 "drm_encoder B" -> "drm_connector B" 53 "drm_encoder B" -> "drm_connector B"
54 } 54 }
55 } 55 }
56 56
57 The basic object structure KMS presents to use 57 The basic object structure KMS presents to userspace is fairly simple.
58 Framebuffers (represented by :c:type:`struct d 58 Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
59 see `Frame Buffer Abstraction`_) feed into pla !! 59 see `Frame Buffer Abstraction`_) feed into planes. One or more (or even no)
60 :c:type:`struct drm_plane <drm_plane>`, see `P !! 60 planes feed their pixel data into a CRTC (represented by :c:type:`struct
61 details. One or more (or even no) planes feed !! 61 drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise
62 (represented by :c:type:`struct drm_crtc <drm_ !! 62 blending step is explained in more detail in `Plane Composition Properties`_ and
63 for blending. The precise blending step is exp !! 63 related chapters.
64 Composition Properties`_ and related chapters. <<
65 64
66 For the output routing the first step is encod 65 For the output routing the first step is encoders (represented by
67 :c:type:`struct drm_encoder <drm_encoder>`, se 66 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
68 are really just internal artifacts of the help 67 are really just internal artifacts of the helper libraries used to implement KMS
69 drivers. Besides that they make it unnecessari !! 68 drivers. Besides that they make it unecessarily more complicated for userspace
70 to figure out which connections between a CRTC 69 to figure out which connections between a CRTC and a connector are possible, and
71 what kind of cloning is supported, they serve 70 what kind of cloning is supported, they serve no purpose in the userspace API.
72 Unfortunately encoders have been exposed to us 71 Unfortunately encoders have been exposed to userspace, hence can't remove them
73 at this point. Furthermore the exposed restri !! 72 at this point. Futhermore the exposed restrictions are often wrongly set by
74 drivers, and in many cases not powerful enough 73 drivers, and in many cases not powerful enough to express the real restrictions.
75 A CRTC can be connected to multiple encoders, 74 A CRTC can be connected to multiple encoders, and for an active CRTC there must
76 be at least one encoder. 75 be at least one encoder.
77 76
78 The final, and real, endpoint in the display c 77 The final, and real, endpoint in the display chain is the connector (represented
79 by :c:type:`struct drm_connector <drm_connecto 78 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
80 Abstraction`_). Connectors can have different 79 Abstraction`_). Connectors can have different possible encoders, but the kernel
81 driver selects which encoder to use for each c 80 driver selects which encoder to use for each connector. The use case is DVI,
82 which could switch between an analog and a dig 81 which could switch between an analog and a digital encoder. Encoders can also
83 drive multiple different connectors. There is 82 drive multiple different connectors. There is exactly one active connector for
84 every active encoder. 83 every active encoder.
85 84
86 Internally the output pipeline is a bit more c 85 Internally the output pipeline is a bit more complex and matches today's
87 hardware more closely: 86 hardware more closely:
88 87
89 .. kernel-render:: DOT 88 .. kernel-render:: DOT
90 :alt: KMS Output Pipeline 89 :alt: KMS Output Pipeline
91 :caption: KMS Output Pipeline 90 :caption: KMS Output Pipeline
92 91
93 digraph "Output Pipeline" { 92 digraph "Output Pipeline" {
94 node [shape=box] 93 node [shape=box]
95 94
96 subgraph { 95 subgraph {
97 "drm_crtc" [bgcolor=grey style=fille 96 "drm_crtc" [bgcolor=grey style=filled]
98 } 97 }
99 98
100 subgraph cluster_internal { 99 subgraph cluster_internal {
101 style=dashed 100 style=dashed
102 label="Internal Pipeline" 101 label="Internal Pipeline"
103 { 102 {
104 node [bgcolor=grey style=filled] 103 node [bgcolor=grey style=filled]
105 "drm_encoder A"; 104 "drm_encoder A";
106 "drm_encoder B"; 105 "drm_encoder B";
107 "drm_encoder C"; 106 "drm_encoder C";
108 } 107 }
109 108
110 { 109 {
111 node [bgcolor=grey style=filled] 110 node [bgcolor=grey style=filled]
112 "drm_encoder B" -> "drm_bridge B 111 "drm_encoder B" -> "drm_bridge B"
113 "drm_encoder C" -> "drm_bridge C 112 "drm_encoder C" -> "drm_bridge C1"
114 "drm_bridge C1" -> "drm_bridge C 113 "drm_bridge C1" -> "drm_bridge C2";
115 } 114 }
116 } 115 }
117 116
118 "drm_crtc" -> "drm_encoder A" 117 "drm_crtc" -> "drm_encoder A"
119 "drm_crtc" -> "drm_encoder B" 118 "drm_crtc" -> "drm_encoder B"
120 "drm_crtc" -> "drm_encoder C" 119 "drm_crtc" -> "drm_encoder C"
121 120
122 121
123 subgraph cluster_output { 122 subgraph cluster_output {
124 style=dashed 123 style=dashed
125 label="Outputs" 124 label="Outputs"
126 125
127 "drm_encoder A" -> "drm_connector A" 126 "drm_encoder A" -> "drm_connector A";
128 "drm_bridge B" -> "drm_connector B"; 127 "drm_bridge B" -> "drm_connector B";
129 "drm_bridge C2" -> "drm_connector C" 128 "drm_bridge C2" -> "drm_connector C";
130 129
131 "drm_panel" 130 "drm_panel"
132 } 131 }
133 } 132 }
134 133
135 Internally two additional helper objects come 134 Internally two additional helper objects come into play. First, to be able to
136 share code for encoders (sometimes on the same 135 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
137 more :ref:`drm_bridges` (represented by :c:typ 136 more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
138 <drm_bridge>`) can be linked to an encoder. Th 137 <drm_bridge>`) can be linked to an encoder. This link is static and cannot be
139 changed, which means the cross-bar (if there i 138 changed, which means the cross-bar (if there is any) needs to be mapped between
140 the CRTC and any encoders. Often for drivers w 139 the CRTC and any encoders. Often for drivers with bridges there's no code left
141 at the encoder level. Atomic drivers can leave 140 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
142 essentially only leave a dummy routing object 141 essentially only leave a dummy routing object behind, which is needed for
143 backwards compatibility since encoders are exp 142 backwards compatibility since encoders are exposed to userspace.
144 143
145 The second object is for panels, represented b 144 The second object is for panels, represented by :c:type:`struct drm_panel
146 <drm_panel>`, see :ref:`drm_panel_helper`. Pan 145 <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
147 point, but are generally linked to the driver 146 point, but are generally linked to the driver private structure that embeds
148 :c:type:`struct drm_connector <drm_connector>` 147 :c:type:`struct drm_connector <drm_connector>`.
149 148
150 Note that currently the bridge chaining and in 149 Note that currently the bridge chaining and interactions with connectors and
151 panels are still in-flux and not really fully 150 panels are still in-flux and not really fully sorted out yet.
152 151
153 KMS Core Structures and Functions 152 KMS Core Structures and Functions
154 ================================= 153 =================================
155 154
156 .. kernel-doc:: include/drm/drm_mode_config.h 155 .. kernel-doc:: include/drm/drm_mode_config.h
157 :internal: 156 :internal:
158 157
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_confi 158 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
160 :export: 159 :export:
161 160
162 .. _kms_base_object_abstraction: <<
163 <<
164 Modeset Base Object Abstraction 161 Modeset Base Object Abstraction
165 =============================== 162 ===============================
166 163
167 .. kernel-render:: DOT 164 .. kernel-render:: DOT
168 :alt: Mode Objects and Properties 165 :alt: Mode Objects and Properties
169 :caption: Mode Objects and Properties 166 :caption: Mode Objects and Properties
170 167
171 digraph { 168 digraph {
172 node [shape=box] 169 node [shape=box]
173 170
174 "drm_property A" -> "drm_mode_object A" 171 "drm_property A" -> "drm_mode_object A"
175 "drm_property A" -> "drm_mode_object B" 172 "drm_property A" -> "drm_mode_object B"
176 "drm_property B" -> "drm_mode_object A" 173 "drm_property B" -> "drm_mode_object A"
177 } 174 }
178 175
179 The base structure for all KMS objects is :c:t 176 The base structure for all KMS objects is :c:type:`struct drm_mode_object
180 <drm_mode_object>`. One of the base services i 177 <drm_mode_object>`. One of the base services it provides is tracking properties,
181 which are especially important for the atomic 178 which are especially important for the atomic IOCTL (see `Atomic Mode
182 Setting`_). The somewhat surprising part here 179 Setting`_). The somewhat surprising part here is that properties are not
183 directly instantiated on each object, but free 180 directly instantiated on each object, but free-standing mode objects themselves,
184 represented by :c:type:`struct drm_property <d 181 represented by :c:type:`struct drm_property <drm_property>`, which only specify
185 the type and value range of a property. Any gi 182 the type and value range of a property. Any given property can be attached
186 multiple times to different objects using drm_ !! 183 multiple times to different objects using :c:func:`drm_object_attach_property()
>> 184 <drm_object_attach_property>`.
187 185
188 .. kernel-doc:: include/drm/drm_mode_object.h 186 .. kernel-doc:: include/drm/drm_mode_object.h
189 :internal: 187 :internal:
190 188
191 .. kernel-doc:: drivers/gpu/drm/drm_mode_objec 189 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
192 :export: 190 :export:
193 191
194 Atomic Mode Setting 192 Atomic Mode Setting
195 =================== 193 ===================
196 194
197 195
198 .. kernel-render:: DOT 196 .. kernel-render:: DOT
199 :alt: Mode Objects and Properties 197 :alt: Mode Objects and Properties
200 :caption: Mode Objects and Properties 198 :caption: Mode Objects and Properties
201 199
202 digraph { 200 digraph {
203 node [shape=box] 201 node [shape=box]
204 202
205 subgraph cluster_state { 203 subgraph cluster_state {
206 style=dashed 204 style=dashed
207 label="Free-standing state" 205 label="Free-standing state"
208 206
209 "drm_atomic_state" -> "duplicated dr 207 "drm_atomic_state" -> "duplicated drm_plane_state A"
210 "drm_atomic_state" -> "duplicated dr 208 "drm_atomic_state" -> "duplicated drm_plane_state B"
211 "drm_atomic_state" -> "duplicated dr 209 "drm_atomic_state" -> "duplicated drm_crtc_state"
212 "drm_atomic_state" -> "duplicated dr 210 "drm_atomic_state" -> "duplicated drm_connector_state"
213 "drm_atomic_state" -> "duplicated dr 211 "drm_atomic_state" -> "duplicated driver private state"
214 } 212 }
215 213
216 subgraph cluster_current { 214 subgraph cluster_current {
217 style=dashed 215 style=dashed
218 label="Current state" 216 label="Current state"
219 217
220 "drm_device" -> "drm_plane A" 218 "drm_device" -> "drm_plane A"
221 "drm_device" -> "drm_plane B" 219 "drm_device" -> "drm_plane B"
222 "drm_device" -> "drm_crtc" 220 "drm_device" -> "drm_crtc"
223 "drm_device" -> "drm_connector" 221 "drm_device" -> "drm_connector"
224 "drm_device" -> "driver private obje 222 "drm_device" -> "driver private object"
225 223
226 "drm_plane A" -> "drm_plane_state A" 224 "drm_plane A" -> "drm_plane_state A"
227 "drm_plane B" -> "drm_plane_state B" 225 "drm_plane B" -> "drm_plane_state B"
228 "drm_crtc" -> "drm_crtc_state" 226 "drm_crtc" -> "drm_crtc_state"
229 "drm_connector" -> "drm_connector_st 227 "drm_connector" -> "drm_connector_state"
230 "driver private object" -> "driver p 228 "driver private object" -> "driver private state"
231 } 229 }
232 230
233 "drm_atomic_state" -> "drm_device" [labe 231 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
234 "duplicated drm_plane_state A" -> "drm_d 232 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
235 } 233 }
236 234
237 Atomic provides transactional modeset (includi 235 Atomic provides transactional modeset (including planes) updates, but a
238 bit differently from the usual transactional a 236 bit differently from the usual transactional approach of try-commit and
239 rollback: 237 rollback:
240 238
241 - Firstly, no hardware changes are allowed whe 239 - Firstly, no hardware changes are allowed when the commit would fail. This
242 allows us to implement the DRM_MODE_ATOMIC_T 240 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
243 userspace to explore whether certain configu 241 userspace to explore whether certain configurations would work or not.
244 242
245 - This would still allow setting and rollback 243 - This would still allow setting and rollback of just the software state,
246 simplifying conversion of existing drivers. 244 simplifying conversion of existing drivers. But auditing drivers for
247 correctness of the atomic_check code becomes 245 correctness of the atomic_check code becomes really hard with that: Rolling
248 back changes in data structures all over the 246 back changes in data structures all over the place is hard to get right.
249 247
250 - Lastly, for backwards compatibility and to s 248 - Lastly, for backwards compatibility and to support all use-cases, atomic
251 updates need to be incremental and be able t 249 updates need to be incremental and be able to execute in parallel. Hardware
252 doesn't always allow it, but where possible 250 doesn't always allow it, but where possible plane updates on different CRTCs
253 should not interfere, and not get stalled du 251 should not interfere, and not get stalled due to output routing changing on
254 different CRTCs. 252 different CRTCs.
255 253
256 Taken all together there's two consequences fo 254 Taken all together there's two consequences for the atomic design:
257 255
258 - The overall state is split up into per-objec 256 - The overall state is split up into per-object state structures:
259 :c:type:`struct drm_plane_state <drm_plane_s 257 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
260 drm_crtc_state <drm_crtc_state>` for CRTCs a 258 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
261 drm_connector_state <drm_connector_state>` f 259 drm_connector_state <drm_connector_state>` for connectors. These are the only
262 objects with userspace-visible and settable 260 objects with userspace-visible and settable state. For internal state drivers
263 can subclass these structures through embedd !! 261 can subclass these structures through embeddeding, or add entirely new state
264 structures for their globally shared hardwar !! 262 structures for their globally shared hardware functions.
265 drm_private_state<drm_private_state>`. <<
266 263
267 - An atomic update is assembled and validated 264 - An atomic update is assembled and validated as an entirely free-standing pile
268 of structures within the :c:type:`drm_atomic 265 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
269 container. Driver private state structures a !! 266 container. Again drivers can subclass that container for their own state
270 structure; see the next chapter. Only when !! 267 structure tracking needs. Only when a state is committed is it applied to the
271 to the driver and modeset objects. This way !! 268 driver and modeset objects. This way rolling back an update boils down to
272 to releasing memory and unreferencing object !! 269 releasing memory and unreferencing objects like framebuffers.
273 <<
274 Locking of atomic state structures is internal <<
275 drm_modeset_lock <drm_modeset_lock>`. As a gen <<
276 exposed to drivers, instead the right locks sh <<
277 any function that duplicates or peeks into a s <<
278 drm_atomic_get_crtc_state(). Locking only pro <<
279 structure, ordering of committing state change <<
280 :c:type:`struct drm_crtc_commit <drm_crtc_comm <<
281 270
282 Read on in this chapter, and also in :ref:`drm 271 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
283 coverage of specific topics. 272 coverage of specific topics.
284 273
285 Handling Driver Private State <<
286 ----------------------------- <<
287 <<
288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c <<
289 :doc: handling driver private state <<
290 <<
291 Atomic Mode Setting Function Reference 274 Atomic Mode Setting Function Reference
292 -------------------------------------- 275 --------------------------------------
293 276
294 .. kernel-doc:: include/drm/drm_atomic.h 277 .. kernel-doc:: include/drm/drm_atomic.h
295 :internal: 278 :internal:
296 279
297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c 280 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298 :export: 281 :export:
299 282
300 Atomic Mode Setting IOCTL and UAPI Functions <<
301 -------------------------------------------- <<
302 <<
303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap <<
304 :doc: overview <<
305 <<
306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap <<
307 :export: <<
308 <<
309 CRTC Abstraction 283 CRTC Abstraction
310 ================ 284 ================
311 285
312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 286 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313 :doc: overview 287 :doc: overview
314 288
315 CRTC Functions Reference 289 CRTC Functions Reference
316 -------------------------------- 290 --------------------------------
317 291
318 .. kernel-doc:: include/drm/drm_crtc.h 292 .. kernel-doc:: include/drm/drm_crtc.h
319 :internal: 293 :internal:
320 294
321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 295 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
322 :export: 296 :export:
323 297
324 Color Management Functions Reference <<
325 ------------------------------------ <<
326 <<
327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt <<
328 :export: <<
329 <<
330 .. kernel-doc:: include/drm/drm_color_mgmt.h <<
331 :internal: <<
332 <<
333 Frame Buffer Abstraction 298 Frame Buffer Abstraction
334 ======================== 299 ========================
335 300
336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 301 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
337 :doc: overview 302 :doc: overview
338 303
339 Frame Buffer Functions Reference 304 Frame Buffer Functions Reference
340 -------------------------------- 305 --------------------------------
341 306
342 .. kernel-doc:: include/drm/drm_framebuffer.h 307 .. kernel-doc:: include/drm/drm_framebuffer.h
343 :internal: 308 :internal:
344 309
345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 310 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
346 :export: 311 :export:
347 312
348 DRM Format Handling 313 DRM Format Handling
349 =================== 314 ===================
350 315
351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h <<
352 :doc: overview <<
353 <<
354 Format Functions Reference <<
355 -------------------------- <<
356 <<
357 .. kernel-doc:: include/drm/drm_fourcc.h 316 .. kernel-doc:: include/drm/drm_fourcc.h
358 :internal: 317 :internal:
359 318
360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 319 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
361 :export: 320 :export:
362 321
363 .. _kms_dumb_buffer_objects: <<
364 <<
365 Dumb Buffer Objects 322 Dumb Buffer Objects
366 =================== 323 ===================
367 324
368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffe 325 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
369 :doc: overview 326 :doc: overview
370 327
371 Plane Abstraction 328 Plane Abstraction
372 ================= 329 =================
373 330
374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 331 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
375 :doc: overview 332 :doc: overview
376 333
377 Plane Functions Reference 334 Plane Functions Reference
378 ------------------------- 335 -------------------------
379 336
380 .. kernel-doc:: include/drm/drm_plane.h 337 .. kernel-doc:: include/drm/drm_plane.h
381 :internal: 338 :internal:
382 339
383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 340 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
384 :export: 341 :export:
385 342
386 Plane Composition Functions Reference <<
387 ------------------------------------- <<
388 <<
389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c <<
390 :export: <<
391 <<
392 Plane Damage Tracking Functions Reference <<
393 ----------------------------------------- <<
394 <<
395 .. kernel-doc:: drivers/gpu/drm/drm_damage_hel <<
396 :export: <<
397 <<
398 .. kernel-doc:: include/drm/drm_damage_helper. <<
399 :internal: <<
400 <<
401 Plane Panic Feature <<
402 ------------------- <<
403 <<
404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c <<
405 :doc: overview <<
406 <<
407 Plane Panic Functions Reference <<
408 ------------------------------- <<
409 <<
410 .. kernel-doc:: include/drm/drm_panic.h <<
411 :internal: <<
412 <<
413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c <<
414 :export: <<
415 <<
416 Display Modes Function Reference 343 Display Modes Function Reference
417 ================================ 344 ================================
418 345
419 .. kernel-doc:: include/drm/drm_modes.h 346 .. kernel-doc:: include/drm/drm_modes.h
420 :internal: 347 :internal:
421 348
422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c 349 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
423 :export: 350 :export:
424 351
425 Connector Abstraction 352 Connector Abstraction
426 ===================== 353 =====================
427 354
428 .. kernel-doc:: drivers/gpu/drm/drm_connector. 355 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
429 :doc: overview 356 :doc: overview
430 357
431 Connector Functions Reference 358 Connector Functions Reference
432 ----------------------------- 359 -----------------------------
433 360
434 .. kernel-doc:: include/drm/drm_connector.h 361 .. kernel-doc:: include/drm/drm_connector.h
435 :internal: 362 :internal:
436 363
437 .. kernel-doc:: drivers/gpu/drm/drm_connector. 364 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
438 :export: 365 :export:
439 366
440 Writeback Connectors <<
441 -------------------- <<
442 <<
443 .. kernel-doc:: drivers/gpu/drm/drm_writeback. <<
444 :doc: overview <<
445 <<
446 .. kernel-doc:: include/drm/drm_writeback.h <<
447 :internal: <<
448 <<
449 .. kernel-doc:: drivers/gpu/drm/drm_writeback. <<
450 :export: <<
451 <<
452 Encoder Abstraction 367 Encoder Abstraction
453 =================== 368 ===================
454 369
455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 370 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456 :doc: overview 371 :doc: overview
457 372
458 Encoder Functions Reference 373 Encoder Functions Reference
459 --------------------------- 374 ---------------------------
460 375
461 .. kernel-doc:: include/drm/drm_encoder.h 376 .. kernel-doc:: include/drm/drm_encoder.h
462 :internal: 377 :internal:
463 378
464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 379 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
465 :export: 380 :export:
466 381
>> 382 KMS Initialization and Cleanup
>> 383 ==============================
>> 384
>> 385 A KMS device is abstracted and exposed as a set of planes, CRTCs,
>> 386 encoders and connectors. KMS drivers must thus create and initialize all
>> 387 those objects at load time after initializing mode setting.
>> 388
>> 389 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
>> 390 --------------------------------------------
>> 391
>> 392 A CRTC is an abstraction representing a part of the chip that contains a
>> 393 pointer to a scanout buffer. Therefore, the number of CRTCs available
>> 394 determines how many independent scanout buffers can be active at any
>> 395 given time. The CRTC structure contains several fields to support this:
>> 396 a pointer to some video memory (abstracted as a frame buffer object), a
>> 397 display mode, and an (x, y) offset into the video memory to support
>> 398 panning or configurations where one piece of video memory spans multiple
>> 399 CRTCs.
>> 400
>> 401 CRTC Initialization
>> 402 ~~~~~~~~~~~~~~~~~~~
>> 403
>> 404 A KMS device must create and register at least one struct
>> 405 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
>> 406 allocated and zeroed by the driver, possibly as part of a larger
>> 407 structure, and registered with a call to :c:func:`drm_crtc_init()`
>> 408 with a pointer to CRTC functions.
>> 409
>> 410
>> 411 Cleanup
>> 412 -------
>> 413
>> 414 The DRM core manages its objects' lifetime. When an object is not needed
>> 415 anymore the core calls its destroy function, which must clean up and
>> 416 free every resource allocated for the object. Every
>> 417 :c:func:`drm_\*_init()` call must be matched with a corresponding
>> 418 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
>> 419 (:c:func:`drm_crtc_cleanup()`), planes
>> 420 (:c:func:`drm_plane_cleanup()`), encoders
>> 421 (:c:func:`drm_encoder_cleanup()`) and connectors
>> 422 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
>> 423 have been added to sysfs must be removed by a call to
>> 424 :c:func:`drm_connector_unregister()` before calling
>> 425 :c:func:`drm_connector_cleanup()`.
>> 426
>> 427 Connectors state change detection must be cleanup up with a call to
>> 428 :c:func:`drm_kms_helper_poll_fini()`.
>> 429
>> 430 Output discovery and initialization example
>> 431 -------------------------------------------
>> 432
>> 433 .. code-block:: c
>> 434
>> 435 void intel_crt_init(struct drm_device *dev)
>> 436 {
>> 437 struct drm_connector *connector;
>> 438 struct intel_output *intel_output;
>> 439
>> 440 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
>> 441 if (!intel_output)
>> 442 return;
>> 443
>> 444 connector = &intel_output->base;
>> 445 drm_connector_init(dev, &intel_output->base,
>> 446 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
>> 447
>> 448 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
>> 449 DRM_MODE_ENCODER_DAC);
>> 450
>> 451 drm_mode_connector_attach_encoder(&intel_output->base,
>> 452 &intel_output->enc);
>> 453
>> 454 /* Set up the DDC bus. */
>> 455 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
>> 456 if (!intel_output->ddc_bus) {
>> 457 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
>> 458 "failed.\n");
>> 459 return;
>> 460 }
>> 461
>> 462 intel_output->type = INTEL_OUTPUT_ANALOG;
>> 463 connector->interlace_allowed = 0;
>> 464 connector->doublescan_allowed = 0;
>> 465
>> 466 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
>> 467 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
>> 468
>> 469 drm_connector_register(connector);
>> 470 }
>> 471
>> 472 In the example above (taken from the i915 driver), a CRTC, connector and
>> 473 encoder combination is created. A device-specific i2c bus is also
>> 474 created for fetching EDID data and performing monitor detection. Once
>> 475 the process is complete, the new connector is registered with sysfs to
>> 476 make its properties available to applications.
>> 477
467 KMS Locking 478 KMS Locking
468 =========== 479 ===========
469 480
470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 481 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
471 :doc: kms locking 482 :doc: kms locking
472 483
473 .. kernel-doc:: include/drm/drm_modeset_lock.h 484 .. kernel-doc:: include/drm/drm_modeset_lock.h
474 :internal: 485 :internal:
475 486
476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 487 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
477 :export: 488 :export:
478 489
479 KMS Properties 490 KMS Properties
480 ============== 491 ==============
481 492
482 This section of the documentation is primarily <<
483 For the driver APIs, see the other sections. <<
484 <<
485 Requirements <<
486 ------------ <<
487 <<
488 KMS drivers might need to add extra properties <<
489 new property introduced in a driver needs to m <<
490 addition to the one mentioned above: <<
491 <<
492 * It must be standardized, documenting: <<
493 <<
494 * The full, exact, name string; <<
495 * If the property is an enum, all the valid <<
496 * What values are accepted, and what these v <<
497 * What the property does and how it can be u <<
498 * How the property might interact with other <<
499 <<
500 * It must provide a generic helper in the core <<
501 property on the object it attaches to. <<
502 <<
503 * Its content must be decoded by the core and <<
504 associated state structure. That includes an <<
505 to precompute, like struct drm_clip_rect for <<
506 <<
507 * Its initial state must match the behavior pr <<
508 introduction. This might be a fixed value ma <<
509 does, or it may be inherited from the state <<
510 system in during boot. <<
511 <<
512 * An IGT test must be submitted where reasonab <<
513 <<
514 For historical reasons, non-standard, driver-s <<
515 driver wants to add support for one of those p <<
516 new properties apply where possible. Additiona <<
517 match the de facto semantics of the existing p <<
518 Developers of the driver that first added the <<
519 tasks and must ACK the documented behavior if <<
520 <<
521 Property Types and Blob Property Support 493 Property Types and Blob Property Support
522 ---------------------------------------- 494 ----------------------------------------
523 495
524 .. kernel-doc:: drivers/gpu/drm/drm_property.c 496 .. kernel-doc:: drivers/gpu/drm/drm_property.c
525 :doc: overview 497 :doc: overview
526 498
527 .. kernel-doc:: include/drm/drm_property.h 499 .. kernel-doc:: include/drm/drm_property.h
528 :internal: 500 :internal:
529 501
530 .. kernel-doc:: drivers/gpu/drm/drm_property.c 502 .. kernel-doc:: drivers/gpu/drm/drm_property.c
531 :export: 503 :export:
532 504
533 .. _standard_connector_properties: <<
534 <<
535 Standard Connector Properties 505 Standard Connector Properties
536 ----------------------------- 506 -----------------------------
537 507
538 .. kernel-doc:: drivers/gpu/drm/drm_connector. 508 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
539 :doc: standard connector properties 509 :doc: standard connector properties
540 510
541 HDMI Specific Connector Properties <<
542 ---------------------------------- <<
543 <<
544 .. kernel-doc:: drivers/gpu/drm/drm_connector. <<
545 :doc: HDMI connector properties <<
546 <<
547 Analog TV Specific Connector Properties <<
548 --------------------------------------- <<
549 <<
550 .. kernel-doc:: drivers/gpu/drm/drm_connector. <<
551 :doc: Analog TV Connector Properties <<
552 <<
553 Standard CRTC Properties <<
554 ------------------------ <<
555 <<
556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c <<
557 :doc: standard CRTC properties <<
558 <<
559 Standard Plane Properties <<
560 ------------------------- <<
561 <<
562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c <<
563 :doc: standard plane properties <<
564 <<
565 .. _plane_composition_properties: <<
566 <<
567 Plane Composition Properties 511 Plane Composition Properties
568 ---------------------------- 512 ----------------------------
569 513
570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 514 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
571 :doc: overview 515 :doc: overview
572 516
573 .. _damage_tracking_properties: !! 517 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
574 !! 518 :export:
575 Damage Tracking Properties <<
576 -------------------------- <<
577 <<
578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c <<
579 :doc: damage tracking <<
580 519
581 Color Management Properties 520 Color Management Properties
582 --------------------------- 521 ---------------------------
583 522
584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt 523 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
585 :doc: overview 524 :doc: overview
586 525
>> 526 .. kernel-doc:: include/drm/drm_color_mgmt.h
>> 527 :internal:
>> 528
>> 529 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
>> 530 :export:
>> 531
587 Tile Group Property 532 Tile Group Property
588 ------------------- 533 -------------------
589 534
590 .. kernel-doc:: drivers/gpu/drm/drm_connector. 535 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
591 :doc: Tile group 536 :doc: Tile group
592 537
593 Explicit Fencing Properties 538 Explicit Fencing Properties
594 --------------------------- 539 ---------------------------
595 540
596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap !! 541 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
597 :doc: explicit fencing properties 542 :doc: explicit fencing properties
598 543
599 <<
600 Variable Refresh Properties <<
601 --------------------------- <<
602 <<
603 .. kernel-doc:: drivers/gpu/drm/drm_connector. <<
604 :doc: Variable refresh properties <<
605 <<
606 Cursor Hotspot Properties <<
607 --------------------------- <<
608 <<
609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c <<
610 :doc: hotspot properties <<
611 <<
612 Existing KMS Properties 544 Existing KMS Properties
613 ----------------------- 545 -----------------------
614 546
615 The following table gives description of drm p !! 547 The following table gives description of drm properties exposed by
616 modules/drivers. Because this table is very un !! 548 various modules/drivers.
617 properties here. Instead document them in a se <<
618 549
619 .. csv-table:: 550 .. csv-table::
620 :header-rows: 1 551 :header-rows: 1
621 :file: kms-properties.csv 552 :file: kms-properties.csv
622 553
623 Vertical Blanking 554 Vertical Blanking
624 ================= 555 =================
625 556
626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c !! 557 Vertical blanking plays a major role in graphics rendering. To achieve
627 :doc: vblank handling !! 558 tear-free display, users must synchronize page flips and/or rendering to
>> 559 vertical blanking. The DRM API offers ioctls to perform page flips
>> 560 synchronized to vertical blanking and wait for vertical blanking.
>> 561
>> 562 The DRM core handles most of the vertical blanking management logic,
>> 563 which involves filtering out spurious interrupts, keeping race-free
>> 564 blanking counters, coping with counter wrap-around and resets and
>> 565 keeping use counts. It relies on the driver to generate vertical
>> 566 blanking interrupts and optionally provide a hardware vertical blanking
>> 567 counter. Drivers must implement the following operations.
>> 568
>> 569 - int (\*enable_vblank) (struct drm_device \*dev, int crtc); void
>> 570 (\*disable_vblank) (struct drm_device \*dev, int crtc);
>> 571 Enable or disable vertical blanking interrupts for the given CRTC.
>> 572
>> 573 - u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc);
>> 574 Retrieve the value of the vertical blanking counter for the given
>> 575 CRTC. If the hardware maintains a vertical blanking counter its value
>> 576 should be returned. Otherwise drivers can use the
>> 577 :c:func:`drm_vblank_count()` helper function to handle this
>> 578 operation.
>> 579
>> 580 Drivers must initialize the vertical blanking handling core with a call
>> 581 to :c:func:`drm_vblank_init()` in their load operation.
>> 582
>> 583 Vertical blanking interrupts can be enabled by the DRM core or by
>> 584 drivers themselves (for instance to handle page flipping operations).
>> 585 The DRM core maintains a vertical blanking use count to ensure that the
>> 586 interrupts are not disabled while a user still needs them. To increment
>> 587 the use count, drivers call :c:func:`drm_vblank_get()`. Upon
>> 588 return vertical blanking interrupts are guaranteed to be enabled.
>> 589
>> 590 To decrement the use count drivers call
>> 591 :c:func:`drm_vblank_put()`. Only when the use count drops to zero
>> 592 will the DRM core disable the vertical blanking interrupts after a delay
>> 593 by scheduling a timer. The delay is accessible through the
>> 594 vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
>> 595 variable and expressed in milliseconds. Its default value is 5000 ms.
>> 596 Zero means never disable, and a negative value means disable
>> 597 immediately. Drivers may override the behaviour by setting the
>> 598 :c:type:`struct drm_device <drm_device>`
>> 599 vblank_disable_immediate flag, which when set causes vblank interrupts
>> 600 to be disabled immediately regardless of the drm_vblank_offdelay
>> 601 value. The flag should only be set if there's a properly working
>> 602 hardware vblank counter present.
>> 603
>> 604 When a vertical blanking interrupt occurs drivers only need to call the
>> 605 :c:func:`drm_handle_vblank()` function to account for the
>> 606 interrupt.
>> 607
>> 608 Resources allocated by :c:func:`drm_vblank_init()` must be freed
>> 609 with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
>> 610 operation handler.
628 611
629 Vertical Blanking and Interrupt Handling Funct 612 Vertical Blanking and Interrupt Handling Functions Reference
630 ---------------------------------------------- 613 ------------------------------------------------------------
631 614
632 .. kernel-doc:: include/drm/drm_vblank.h 615 .. kernel-doc:: include/drm/drm_vblank.h
633 :internal: 616 :internal:
634 617
635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c 618 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
636 :export: <<
637 <<
638 Vertical Blank Work <<
639 =================== <<
640 <<
641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor <<
642 :doc: vblank works <<
643 <<
644 Vertical Blank Work Functions Reference <<
645 --------------------------------------- <<
646 <<
647 .. kernel-doc:: include/drm/drm_vblank_work.h <<
648 :internal: <<
649 <<
650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor <<
651 :export: 619 :export:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.