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 drmm_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. Planes are represented by
60 :c:type:`struct drm_plane <drm_plane>`, see `P 60 :c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
61 details. One or more (or even no) planes feed 61 details. One or more (or even no) planes feed their pixel data into a CRTC
62 (represented by :c:type:`struct drm_crtc <drm_ 62 (represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_)
63 for blending. The precise blending step is exp 63 for blending. The precise blending step is explained in more detail in `Plane
64 Composition Properties`_ and related chapters. 64 Composition Properties`_ and related chapters.
65 65
66 For the output routing the first step is encod 66 For the output routing the first step is encoders (represented by
67 :c:type:`struct drm_encoder <drm_encoder>`, se 67 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
68 are really just internal artifacts of the help 68 are really just internal artifacts of the helper libraries used to implement KMS
69 drivers. Besides that they make it unnecessari 69 drivers. Besides that they make it unnecessarily more complicated for userspace
70 to figure out which connections between a CRTC 70 to figure out which connections between a CRTC and a connector are possible, and
71 what kind of cloning is supported, they serve 71 what kind of cloning is supported, they serve no purpose in the userspace API.
72 Unfortunately encoders have been exposed to us 72 Unfortunately encoders have been exposed to userspace, hence can't remove them
73 at this point. Furthermore the exposed restri 73 at this point. Furthermore the exposed restrictions are often wrongly set by
74 drivers, and in many cases not powerful enough 74 drivers, and in many cases not powerful enough to express the real restrictions.
75 A CRTC can be connected to multiple encoders, 75 A CRTC can be connected to multiple encoders, and for an active CRTC there must
76 be at least one encoder. 76 be at least one encoder.
77 77
78 The final, and real, endpoint in the display c 78 The final, and real, endpoint in the display chain is the connector (represented
79 by :c:type:`struct drm_connector <drm_connecto 79 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
80 Abstraction`_). Connectors can have different 80 Abstraction`_). Connectors can have different possible encoders, but the kernel
81 driver selects which encoder to use for each c 81 driver selects which encoder to use for each connector. The use case is DVI,
82 which could switch between an analog and a dig 82 which could switch between an analog and a digital encoder. Encoders can also
83 drive multiple different connectors. There is 83 drive multiple different connectors. There is exactly one active connector for
84 every active encoder. 84 every active encoder.
85 85
86 Internally the output pipeline is a bit more c 86 Internally the output pipeline is a bit more complex and matches today's
87 hardware more closely: 87 hardware more closely:
88 88
89 .. kernel-render:: DOT 89 .. kernel-render:: DOT
90 :alt: KMS Output Pipeline 90 :alt: KMS Output Pipeline
91 :caption: KMS Output Pipeline 91 :caption: KMS Output Pipeline
92 92
93 digraph "Output Pipeline" { 93 digraph "Output Pipeline" {
94 node [shape=box] 94 node [shape=box]
95 95
96 subgraph { 96 subgraph {
97 "drm_crtc" [bgcolor=grey style=fille 97 "drm_crtc" [bgcolor=grey style=filled]
98 } 98 }
99 99
100 subgraph cluster_internal { 100 subgraph cluster_internal {
101 style=dashed 101 style=dashed
102 label="Internal Pipeline" 102 label="Internal Pipeline"
103 { 103 {
104 node [bgcolor=grey style=filled] 104 node [bgcolor=grey style=filled]
105 "drm_encoder A"; 105 "drm_encoder A";
106 "drm_encoder B"; 106 "drm_encoder B";
107 "drm_encoder C"; 107 "drm_encoder C";
108 } 108 }
109 109
110 { 110 {
111 node [bgcolor=grey style=filled] 111 node [bgcolor=grey style=filled]
112 "drm_encoder B" -> "drm_bridge B 112 "drm_encoder B" -> "drm_bridge B"
113 "drm_encoder C" -> "drm_bridge C 113 "drm_encoder C" -> "drm_bridge C1"
114 "drm_bridge C1" -> "drm_bridge C 114 "drm_bridge C1" -> "drm_bridge C2";
115 } 115 }
116 } 116 }
117 117
118 "drm_crtc" -> "drm_encoder A" 118 "drm_crtc" -> "drm_encoder A"
119 "drm_crtc" -> "drm_encoder B" 119 "drm_crtc" -> "drm_encoder B"
120 "drm_crtc" -> "drm_encoder C" 120 "drm_crtc" -> "drm_encoder C"
121 121
122 122
123 subgraph cluster_output { 123 subgraph cluster_output {
124 style=dashed 124 style=dashed
125 label="Outputs" 125 label="Outputs"
126 126
127 "drm_encoder A" -> "drm_connector A" 127 "drm_encoder A" -> "drm_connector A";
128 "drm_bridge B" -> "drm_connector B"; 128 "drm_bridge B" -> "drm_connector B";
129 "drm_bridge C2" -> "drm_connector C" 129 "drm_bridge C2" -> "drm_connector C";
130 130
131 "drm_panel" 131 "drm_panel"
132 } 132 }
133 } 133 }
134 134
135 Internally two additional helper objects come 135 Internally two additional helper objects come into play. First, to be able to
136 share code for encoders (sometimes on the same 136 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
137 more :ref:`drm_bridges` (represented by :c:typ 137 more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
138 <drm_bridge>`) can be linked to an encoder. Th 138 <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 139 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 140 the CRTC and any encoders. Often for drivers with bridges there's no code left
141 at the encoder level. Atomic drivers can leave 141 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
142 essentially only leave a dummy routing object 142 essentially only leave a dummy routing object behind, which is needed for
143 backwards compatibility since encoders are exp 143 backwards compatibility since encoders are exposed to userspace.
144 144
145 The second object is for panels, represented b 145 The second object is for panels, represented by :c:type:`struct drm_panel
146 <drm_panel>`, see :ref:`drm_panel_helper`. Pan 146 <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
147 point, but are generally linked to the driver 147 point, but are generally linked to the driver private structure that embeds
148 :c:type:`struct drm_connector <drm_connector>` 148 :c:type:`struct drm_connector <drm_connector>`.
149 149
150 Note that currently the bridge chaining and in 150 Note that currently the bridge chaining and interactions with connectors and
151 panels are still in-flux and not really fully 151 panels are still in-flux and not really fully sorted out yet.
152 152
153 KMS Core Structures and Functions 153 KMS Core Structures and Functions
154 ================================= 154 =================================
155 155
156 .. kernel-doc:: include/drm/drm_mode_config.h 156 .. kernel-doc:: include/drm/drm_mode_config.h
157 :internal: 157 :internal:
158 158
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_confi 159 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
160 :export: 160 :export:
161 161
162 .. _kms_base_object_abstraction: 162 .. _kms_base_object_abstraction:
163 163
164 Modeset Base Object Abstraction 164 Modeset Base Object Abstraction
165 =============================== 165 ===============================
166 166
167 .. kernel-render:: DOT 167 .. kernel-render:: DOT
168 :alt: Mode Objects and Properties 168 :alt: Mode Objects and Properties
169 :caption: Mode Objects and Properties 169 :caption: Mode Objects and Properties
170 170
171 digraph { 171 digraph {
172 node [shape=box] 172 node [shape=box]
173 173
174 "drm_property A" -> "drm_mode_object A" 174 "drm_property A" -> "drm_mode_object A"
175 "drm_property A" -> "drm_mode_object B" 175 "drm_property A" -> "drm_mode_object B"
176 "drm_property B" -> "drm_mode_object A" 176 "drm_property B" -> "drm_mode_object A"
177 } 177 }
178 178
179 The base structure for all KMS objects is :c:t 179 The base structure for all KMS objects is :c:type:`struct drm_mode_object
180 <drm_mode_object>`. One of the base services i 180 <drm_mode_object>`. One of the base services it provides is tracking properties,
181 which are especially important for the atomic 181 which are especially important for the atomic IOCTL (see `Atomic Mode
182 Setting`_). The somewhat surprising part here 182 Setting`_). The somewhat surprising part here is that properties are not
183 directly instantiated on each object, but free 183 directly instantiated on each object, but free-standing mode objects themselves,
184 represented by :c:type:`struct drm_property <d 184 represented by :c:type:`struct drm_property <drm_property>`, which only specify
185 the type and value range of a property. Any gi 185 the type and value range of a property. Any given property can be attached
186 multiple times to different objects using drm_ 186 multiple times to different objects using drm_object_attach_property().
187 187
188 .. kernel-doc:: include/drm/drm_mode_object.h 188 .. kernel-doc:: include/drm/drm_mode_object.h
189 :internal: 189 :internal:
190 190
191 .. kernel-doc:: drivers/gpu/drm/drm_mode_objec 191 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
192 :export: 192 :export:
193 193
194 Atomic Mode Setting 194 Atomic Mode Setting
195 =================== 195 ===================
196 196
197 197
198 .. kernel-render:: DOT 198 .. kernel-render:: DOT
199 :alt: Mode Objects and Properties 199 :alt: Mode Objects and Properties
200 :caption: Mode Objects and Properties 200 :caption: Mode Objects and Properties
201 201
202 digraph { 202 digraph {
203 node [shape=box] 203 node [shape=box]
204 204
205 subgraph cluster_state { 205 subgraph cluster_state {
206 style=dashed 206 style=dashed
207 label="Free-standing state" 207 label="Free-standing state"
208 208
209 "drm_atomic_state" -> "duplicated dr 209 "drm_atomic_state" -> "duplicated drm_plane_state A"
210 "drm_atomic_state" -> "duplicated dr 210 "drm_atomic_state" -> "duplicated drm_plane_state B"
211 "drm_atomic_state" -> "duplicated dr 211 "drm_atomic_state" -> "duplicated drm_crtc_state"
212 "drm_atomic_state" -> "duplicated dr 212 "drm_atomic_state" -> "duplicated drm_connector_state"
213 "drm_atomic_state" -> "duplicated dr 213 "drm_atomic_state" -> "duplicated driver private state"
214 } 214 }
215 215
216 subgraph cluster_current { 216 subgraph cluster_current {
217 style=dashed 217 style=dashed
218 label="Current state" 218 label="Current state"
219 219
220 "drm_device" -> "drm_plane A" 220 "drm_device" -> "drm_plane A"
221 "drm_device" -> "drm_plane B" 221 "drm_device" -> "drm_plane B"
222 "drm_device" -> "drm_crtc" 222 "drm_device" -> "drm_crtc"
223 "drm_device" -> "drm_connector" 223 "drm_device" -> "drm_connector"
224 "drm_device" -> "driver private obje 224 "drm_device" -> "driver private object"
225 225
226 "drm_plane A" -> "drm_plane_state A" 226 "drm_plane A" -> "drm_plane_state A"
227 "drm_plane B" -> "drm_plane_state B" 227 "drm_plane B" -> "drm_plane_state B"
228 "drm_crtc" -> "drm_crtc_state" 228 "drm_crtc" -> "drm_crtc_state"
229 "drm_connector" -> "drm_connector_st 229 "drm_connector" -> "drm_connector_state"
230 "driver private object" -> "driver p 230 "driver private object" -> "driver private state"
231 } 231 }
232 232
233 "drm_atomic_state" -> "drm_device" [labe 233 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
234 "duplicated drm_plane_state A" -> "drm_d 234 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
235 } 235 }
236 236
237 Atomic provides transactional modeset (includi 237 Atomic provides transactional modeset (including planes) updates, but a
238 bit differently from the usual transactional a 238 bit differently from the usual transactional approach of try-commit and
239 rollback: 239 rollback:
240 240
241 - Firstly, no hardware changes are allowed whe 241 - Firstly, no hardware changes are allowed when the commit would fail. This
242 allows us to implement the DRM_MODE_ATOMIC_T 242 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
243 userspace to explore whether certain configu 243 userspace to explore whether certain configurations would work or not.
244 244
245 - This would still allow setting and rollback 245 - This would still allow setting and rollback of just the software state,
246 simplifying conversion of existing drivers. 246 simplifying conversion of existing drivers. But auditing drivers for
247 correctness of the atomic_check code becomes 247 correctness of the atomic_check code becomes really hard with that: Rolling
248 back changes in data structures all over the 248 back changes in data structures all over the place is hard to get right.
249 249
250 - Lastly, for backwards compatibility and to s 250 - Lastly, for backwards compatibility and to support all use-cases, atomic
251 updates need to be incremental and be able t 251 updates need to be incremental and be able to execute in parallel. Hardware
252 doesn't always allow it, but where possible 252 doesn't always allow it, but where possible plane updates on different CRTCs
253 should not interfere, and not get stalled du 253 should not interfere, and not get stalled due to output routing changing on
254 different CRTCs. 254 different CRTCs.
255 255
256 Taken all together there's two consequences fo 256 Taken all together there's two consequences for the atomic design:
257 257
258 - The overall state is split up into per-objec 258 - The overall state is split up into per-object state structures:
259 :c:type:`struct drm_plane_state <drm_plane_s 259 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
260 drm_crtc_state <drm_crtc_state>` for CRTCs a 260 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
261 drm_connector_state <drm_connector_state>` f 261 drm_connector_state <drm_connector_state>` for connectors. These are the only
262 objects with userspace-visible and settable 262 objects with userspace-visible and settable state. For internal state drivers
263 can subclass these structures through embedd 263 can subclass these structures through embedding, or add entirely new state
264 structures for their globally shared hardwar 264 structures for their globally shared hardware functions, see :c:type:`struct
265 drm_private_state<drm_private_state>`. 265 drm_private_state<drm_private_state>`.
266 266
267 - An atomic update is assembled and validated 267 - An atomic update is assembled and validated as an entirely free-standing pile
268 of structures within the :c:type:`drm_atomic 268 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
269 container. Driver private state structures a 269 container. Driver private state structures are also tracked in the same
270 structure; see the next chapter. Only when 270 structure; see the next chapter. Only when a state is committed is it applied
271 to the driver and modeset objects. This way 271 to the driver and modeset objects. This way rolling back an update boils down
272 to releasing memory and unreferencing object 272 to releasing memory and unreferencing objects like framebuffers.
273 273
274 Locking of atomic state structures is internal 274 Locking of atomic state structures is internally using :c:type:`struct
275 drm_modeset_lock <drm_modeset_lock>`. As a gen 275 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
276 exposed to drivers, instead the right locks sh 276 exposed to drivers, instead the right locks should be automatically acquired by
277 any function that duplicates or peeks into a s 277 any function that duplicates or peeks into a state, like e.g.
278 drm_atomic_get_crtc_state(). Locking only pro 278 drm_atomic_get_crtc_state(). Locking only protects the software data
279 structure, ordering of committing state change 279 structure, ordering of committing state changes to hardware is sequenced using
280 :c:type:`struct drm_crtc_commit <drm_crtc_comm 280 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
281 281
282 Read on in this chapter, and also in :ref:`drm 282 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
283 coverage of specific topics. 283 coverage of specific topics.
284 284
285 Handling Driver Private State 285 Handling Driver Private State
286 ----------------------------- 286 -----------------------------
287 287
288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c 288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
289 :doc: handling driver private state 289 :doc: handling driver private state
290 290
291 Atomic Mode Setting Function Reference 291 Atomic Mode Setting Function Reference
292 -------------------------------------- 292 --------------------------------------
293 293
294 .. kernel-doc:: include/drm/drm_atomic.h 294 .. kernel-doc:: include/drm/drm_atomic.h
295 :internal: 295 :internal:
296 296
297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c 297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298 :export: 298 :export:
299 299
300 Atomic Mode Setting IOCTL and UAPI Functions 300 Atomic Mode Setting IOCTL and UAPI Functions
301 -------------------------------------------- 301 --------------------------------------------
302 302
303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap 303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
304 :doc: overview 304 :doc: overview
305 305
306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap 306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
307 :export: 307 :export:
308 308
309 CRTC Abstraction 309 CRTC Abstraction
310 ================ 310 ================
311 311
312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313 :doc: overview 313 :doc: overview
314 314
315 CRTC Functions Reference 315 CRTC Functions Reference
316 -------------------------------- 316 --------------------------------
317 317
318 .. kernel-doc:: include/drm/drm_crtc.h 318 .. kernel-doc:: include/drm/drm_crtc.h
319 :internal: 319 :internal:
320 320
321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
322 :export: 322 :export:
323 323
324 Color Management Functions Reference 324 Color Management Functions Reference
325 ------------------------------------ 325 ------------------------------------
326 326
327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt 327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
328 :export: 328 :export:
329 329
330 .. kernel-doc:: include/drm/drm_color_mgmt.h 330 .. kernel-doc:: include/drm/drm_color_mgmt.h
331 :internal: 331 :internal:
332 332
333 Frame Buffer Abstraction 333 Frame Buffer Abstraction
334 ======================== 334 ========================
335 335
336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
337 :doc: overview 337 :doc: overview
338 338
339 Frame Buffer Functions Reference 339 Frame Buffer Functions Reference
340 -------------------------------- 340 --------------------------------
341 341
342 .. kernel-doc:: include/drm/drm_framebuffer.h 342 .. kernel-doc:: include/drm/drm_framebuffer.h
343 :internal: 343 :internal:
344 344
345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
346 :export: 346 :export:
347 347
348 DRM Format Handling 348 DRM Format Handling
349 =================== 349 ===================
350 350
351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h 351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
352 :doc: overview 352 :doc: overview
353 353
354 Format Functions Reference 354 Format Functions Reference
355 -------------------------- 355 --------------------------
356 356
357 .. kernel-doc:: include/drm/drm_fourcc.h 357 .. kernel-doc:: include/drm/drm_fourcc.h
358 :internal: 358 :internal:
359 359
360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
361 :export: 361 :export:
362 362
363 .. _kms_dumb_buffer_objects: 363 .. _kms_dumb_buffer_objects:
364 364
365 Dumb Buffer Objects 365 Dumb Buffer Objects
366 =================== 366 ===================
367 367
368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffe 368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
369 :doc: overview 369 :doc: overview
370 370
371 Plane Abstraction 371 Plane Abstraction
372 ================= 372 =================
373 373
374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
375 :doc: overview 375 :doc: overview
376 376
377 Plane Functions Reference 377 Plane Functions Reference
378 ------------------------- 378 -------------------------
379 379
380 .. kernel-doc:: include/drm/drm_plane.h 380 .. kernel-doc:: include/drm/drm_plane.h
381 :internal: 381 :internal:
382 382
383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
384 :export: 384 :export:
385 385
386 Plane Composition Functions Reference 386 Plane Composition Functions Reference
387 ------------------------------------- 387 -------------------------------------
388 388
389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
390 :export: 390 :export:
391 391
392 Plane Damage Tracking Functions Reference 392 Plane Damage Tracking Functions Reference
393 ----------------------------------------- 393 -----------------------------------------
394 394
395 .. kernel-doc:: drivers/gpu/drm/drm_damage_hel 395 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
396 :export: 396 :export:
397 397
398 .. kernel-doc:: include/drm/drm_damage_helper. 398 .. kernel-doc:: include/drm/drm_damage_helper.h
399 :internal: 399 :internal:
400 400
401 Plane Panic Feature 401 Plane Panic Feature
402 ------------------- 402 -------------------
403 403
404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c 404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
405 :doc: overview 405 :doc: overview
406 406
407 Plane Panic Functions Reference 407 Plane Panic Functions Reference
408 ------------------------------- 408 -------------------------------
409 409
410 .. kernel-doc:: include/drm/drm_panic.h 410 .. kernel-doc:: include/drm/drm_panic.h
411 :internal: 411 :internal:
412 412
413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c 413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
414 :export: 414 :export:
415 415
416 Display Modes Function Reference 416 Display Modes Function Reference
417 ================================ 417 ================================
418 418
419 .. kernel-doc:: include/drm/drm_modes.h 419 .. kernel-doc:: include/drm/drm_modes.h
420 :internal: 420 :internal:
421 421
422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c 422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
423 :export: 423 :export:
424 424
425 Connector Abstraction 425 Connector Abstraction
426 ===================== 426 =====================
427 427
428 .. kernel-doc:: drivers/gpu/drm/drm_connector. 428 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
429 :doc: overview 429 :doc: overview
430 430
431 Connector Functions Reference 431 Connector Functions Reference
432 ----------------------------- 432 -----------------------------
433 433
434 .. kernel-doc:: include/drm/drm_connector.h 434 .. kernel-doc:: include/drm/drm_connector.h
435 :internal: 435 :internal:
436 436
437 .. kernel-doc:: drivers/gpu/drm/drm_connector. 437 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
438 :export: 438 :export:
439 439
440 Writeback Connectors 440 Writeback Connectors
441 -------------------- 441 --------------------
442 442
443 .. kernel-doc:: drivers/gpu/drm/drm_writeback. 443 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
444 :doc: overview 444 :doc: overview
445 445
446 .. kernel-doc:: include/drm/drm_writeback.h 446 .. kernel-doc:: include/drm/drm_writeback.h
447 :internal: 447 :internal:
448 448
449 .. kernel-doc:: drivers/gpu/drm/drm_writeback. 449 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
450 :export: 450 :export:
451 451
452 Encoder Abstraction 452 Encoder Abstraction
453 =================== 453 ===================
454 454
455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456 :doc: overview 456 :doc: overview
457 457
458 Encoder Functions Reference 458 Encoder Functions Reference
459 --------------------------- 459 ---------------------------
460 460
461 .. kernel-doc:: include/drm/drm_encoder.h 461 .. kernel-doc:: include/drm/drm_encoder.h
462 :internal: 462 :internal:
463 463
464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
465 :export: 465 :export:
466 466
467 KMS Locking 467 KMS Locking
468 =========== 468 ===========
469 469
470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
471 :doc: kms locking 471 :doc: kms locking
472 472
473 .. kernel-doc:: include/drm/drm_modeset_lock.h 473 .. kernel-doc:: include/drm/drm_modeset_lock.h
474 :internal: 474 :internal:
475 475
476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
477 :export: 477 :export:
478 478
479 KMS Properties 479 KMS Properties
480 ============== 480 ==============
481 481
482 This section of the documentation is primarily 482 This section of the documentation is primarily aimed at user-space developers.
483 For the driver APIs, see the other sections. 483 For the driver APIs, see the other sections.
484 484
485 Requirements 485 Requirements
486 ------------ 486 ------------
487 487
488 KMS drivers might need to add extra properties 488 KMS drivers might need to add extra properties to support new features. Each
489 new property introduced in a driver needs to m 489 new property introduced in a driver needs to meet a few requirements, in
490 addition to the one mentioned above: 490 addition to the one mentioned above:
491 491
492 * It must be standardized, documenting: 492 * It must be standardized, documenting:
493 493
494 * The full, exact, name string; 494 * The full, exact, name string;
495 * If the property is an enum, all the valid 495 * If the property is an enum, all the valid value name strings;
496 * What values are accepted, and what these v 496 * What values are accepted, and what these values mean;
497 * What the property does and how it can be u 497 * What the property does and how it can be used;
498 * How the property might interact with other 498 * How the property might interact with other, existing properties.
499 499
500 * It must provide a generic helper in the core 500 * It must provide a generic helper in the core code to register that
501 property on the object it attaches to. 501 property on the object it attaches to.
502 502
503 * Its content must be decoded by the core and 503 * Its content must be decoded by the core and provided in the object's
504 associated state structure. That includes an 504 associated state structure. That includes anything drivers might want
505 to precompute, like struct drm_clip_rect for 505 to precompute, like struct drm_clip_rect for planes.
506 506
507 * Its initial state must match the behavior pr 507 * Its initial state must match the behavior prior to the property
508 introduction. This might be a fixed value ma 508 introduction. This might be a fixed value matching what the hardware
509 does, or it may be inherited from the state 509 does, or it may be inherited from the state the firmware left the
510 system in during boot. 510 system in during boot.
511 511
512 * An IGT test must be submitted where reasonab 512 * An IGT test must be submitted where reasonable.
513 513
514 For historical reasons, non-standard, driver-s 514 For historical reasons, non-standard, driver-specific properties exist. If a KMS
515 driver wants to add support for one of those p 515 driver wants to add support for one of those properties, the requirements for
516 new properties apply where possible. Additiona 516 new properties apply where possible. Additionally, the documented behavior must
517 match the de facto semantics of the existing p 517 match the de facto semantics of the existing property to ensure compatibility.
518 Developers of the driver that first added the 518 Developers of the driver that first added the property should help with those
519 tasks and must ACK the documented behavior if 519 tasks and must ACK the documented behavior if possible.
520 520
521 Property Types and Blob Property Support 521 Property Types and Blob Property Support
522 ---------------------------------------- 522 ----------------------------------------
523 523
524 .. kernel-doc:: drivers/gpu/drm/drm_property.c 524 .. kernel-doc:: drivers/gpu/drm/drm_property.c
525 :doc: overview 525 :doc: overview
526 526
527 .. kernel-doc:: include/drm/drm_property.h 527 .. kernel-doc:: include/drm/drm_property.h
528 :internal: 528 :internal:
529 529
530 .. kernel-doc:: drivers/gpu/drm/drm_property.c 530 .. kernel-doc:: drivers/gpu/drm/drm_property.c
531 :export: 531 :export:
532 532
533 .. _standard_connector_properties: 533 .. _standard_connector_properties:
534 534
535 Standard Connector Properties 535 Standard Connector Properties
536 ----------------------------- 536 -----------------------------
537 537
538 .. kernel-doc:: drivers/gpu/drm/drm_connector. 538 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
539 :doc: standard connector properties 539 :doc: standard connector properties
540 540
541 HDMI Specific Connector Properties 541 HDMI Specific Connector Properties
542 ---------------------------------- 542 ----------------------------------
543 543
544 .. kernel-doc:: drivers/gpu/drm/drm_connector. 544 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
545 :doc: HDMI connector properties 545 :doc: HDMI connector properties
546 546
547 Analog TV Specific Connector Properties 547 Analog TV Specific Connector Properties
548 --------------------------------------- 548 ---------------------------------------
549 549
550 .. kernel-doc:: drivers/gpu/drm/drm_connector. 550 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
551 :doc: Analog TV Connector Properties 551 :doc: Analog TV Connector Properties
552 552
553 Standard CRTC Properties 553 Standard CRTC Properties
554 ------------------------ 554 ------------------------
555 555
556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
557 :doc: standard CRTC properties 557 :doc: standard CRTC properties
558 558
559 Standard Plane Properties 559 Standard Plane Properties
560 ------------------------- 560 -------------------------
561 561
562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
563 :doc: standard plane properties 563 :doc: standard plane properties
564 564
565 .. _plane_composition_properties: 565 .. _plane_composition_properties:
566 566
567 Plane Composition Properties 567 Plane Composition Properties
568 ---------------------------- 568 ----------------------------
569 569
570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
571 :doc: overview 571 :doc: overview
572 572
573 .. _damage_tracking_properties: 573 .. _damage_tracking_properties:
574 574
575 Damage Tracking Properties 575 Damage Tracking Properties
576 -------------------------- 576 --------------------------
577 577
578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
579 :doc: damage tracking 579 :doc: damage tracking
580 580
581 Color Management Properties 581 Color Management Properties
582 --------------------------- 582 ---------------------------
583 583
584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt 584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
585 :doc: overview 585 :doc: overview
586 586
587 Tile Group Property 587 Tile Group Property
588 ------------------- 588 -------------------
589 589
590 .. kernel-doc:: drivers/gpu/drm/drm_connector. 590 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
591 :doc: Tile group 591 :doc: Tile group
592 592
593 Explicit Fencing Properties 593 Explicit Fencing Properties
594 --------------------------- 594 ---------------------------
595 595
596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap 596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
597 :doc: explicit fencing properties 597 :doc: explicit fencing properties
598 598
599 599
600 Variable Refresh Properties 600 Variable Refresh Properties
601 --------------------------- 601 ---------------------------
602 602
603 .. kernel-doc:: drivers/gpu/drm/drm_connector. 603 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
604 :doc: Variable refresh properties 604 :doc: Variable refresh properties
605 605
606 Cursor Hotspot Properties 606 Cursor Hotspot Properties
607 --------------------------- 607 ---------------------------
608 608
609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
610 :doc: hotspot properties 610 :doc: hotspot properties
611 611
612 Existing KMS Properties 612 Existing KMS Properties
613 ----------------------- 613 -----------------------
614 614
615 The following table gives description of drm p 615 The following table gives description of drm properties exposed by various
616 modules/drivers. Because this table is very un 616 modules/drivers. Because this table is very unwieldy, do not add any new
617 properties here. Instead document them in a se 617 properties here. Instead document them in a section above.
618 618
619 .. csv-table:: 619 .. csv-table::
620 :header-rows: 1 620 :header-rows: 1
621 :file: kms-properties.csv 621 :file: kms-properties.csv
622 622
623 Vertical Blanking 623 Vertical Blanking
624 ================= 624 =================
625 625
626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c 626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
627 :doc: vblank handling 627 :doc: vblank handling
628 628
629 Vertical Blanking and Interrupt Handling Funct 629 Vertical Blanking and Interrupt Handling Functions Reference
630 ---------------------------------------------- 630 ------------------------------------------------------------
631 631
632 .. kernel-doc:: include/drm/drm_vblank.h 632 .. kernel-doc:: include/drm/drm_vblank.h
633 :internal: 633 :internal:
634 634
635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c 635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
636 :export: 636 :export:
637 637
638 Vertical Blank Work 638 Vertical Blank Work
639 =================== 639 ===================
640 640
641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor 641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
642 :doc: vblank works 642 :doc: vblank works
643 643
644 Vertical Blank Work Functions Reference 644 Vertical Blank Work Functions Reference
645 --------------------------------------- 645 ---------------------------------------
646 646
647 .. kernel-doc:: include/drm/drm_vblank_work.h 647 .. kernel-doc:: include/drm/drm_vblank_work.h
648 :internal: 648 :internal:
649 649
650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor 650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
651 :export: 651 :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.