1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==============================
4 drm/komeda Arm display driver
5 ==============================
6
7 The drm/komeda driver supports the Arm display
8 this document gives a brief overview of driver
9 design it like that.
10
11 Overview of D71 like display IPs
12 ================================
13
14 From D71, Arm display IP begins to adopt a fle
15 architecture. A display pipeline is made up of
16 functional pipeline stages called components,
17 specific capabilities that can give the flowed
18 particular processing.
19
20 Typical D71 components:
21
22 Layer
23 -----
24 Layer is the first pipeline stage, which prepa
25 stage. It fetches the pixel from memory, decod
26 source image, unpacks or converts YUV pixels t
27 then adjusts the color_space of pixels if need
28
29 Scaler
30 ------
31 As its name suggests, scaler takes responsibil
32 supports image enhancements by scaler.
33 The usage of scaler is very flexible and can b
34 for layer scaling, or connected to compositor
35 frame and then feed the output data into wb_la
36 into memory.
37
38 Compositor (compiz)
39 -------------------
40 Compositor blends multiple layers or pixel dat
41 frame. its output frame can be fed into post i
42 the monitor or fed into wb_layer and written t
43 user can also insert a scaler between composit
44 the display frame first and then write to memo
45
46 Writeback Layer (wb_layer)
47 --------------------------
48 Writeback layer does the opposite things of La
49 and writes the composition result to memory.
50
51 Post image processor (improc)
52 -----------------------------
53 Post image processor adjusts frame data like g
54 requirements of the monitor.
55
56 Timing controller (timing_ctrlr)
57 --------------------------------
58 Final stage of display pipeline, Timing contro
59 handling, but only for controlling the display
60
61 Merger
62 ------
63 D71 scaler mostly only has the half horizontal
64 compared with Layer, like if Layer supports 4K
65 support 2K input/output in the same time. To a
66 introduces Layer Split, which splits the whole
67 them to two Layers A and B, and does the scali
68 the result need to be fed to merger to merge t
69 output merged result to compiz.
70
71 Splitter
72 --------
73 Similar to Layer Split, but Splitter is used f
74 compiz result to two parts and then feed them
75
76 Possible D71 Pipeline usage
77 ===========================
78
79 Benefitting from the modularized architecture,
80 adjusted to fit different usages. And D71 has
81 types of working mode:
82
83 - Dual display mode
84 Two pipelines work independently and separ
85
86 - Single display mode
87 Two pipelines work together to drive only
88
89 On this mode, pipeline_B doesn't work inde
90 composition result into pipeline_A, and it
91 pipeline_A.timing_ctrlr. The pipeline_B wo
92 pipeline_A(master)
93
94 Single pipeline data flow
95 -------------------------
96
97 .. kernel-render:: DOT
98 :alt: Single pipeline digraph
99 :caption: Single pipeline data flow
100
101 digraph single_ppl {
102 rankdir=LR;
103
104 subgraph {
105 "Memory";
106 "Monitor";
107 }
108
109 subgraph cluster_pipeline {
110 style=dashed
111 node [shape=box]
112 {
113 node [bgcolor=grey style=dashed]
114 "Scaler-0";
115 "Scaler-1";
116 "Scaler-0/1"
117 }
118
119 node [bgcolor=grey style=filled]
120 "Layer-0" -> "Scaler-0"
121 "Layer-1" -> "Scaler-0"
122 "Layer-2" -> "Scaler-1"
123 "Layer-3" -> "Scaler-1"
124
125 "Layer-0" -> "Compiz"
126 "Layer-1" -> "Compiz"
127 "Layer-2" -> "Compiz"
128 "Layer-3" -> "Compiz"
129 "Scaler-0" -> "Compiz"
130 "Scaler-1" -> "Compiz"
131
132 "Compiz" -> "Scaler-0/1" -> "Wb_layer
133 "Compiz" -> "Improc" -> "Timing Contr
134 }
135
136 "Wb_layer" -> "Memory"
137 "Timing Controller" -> "Monitor"
138 }
139
140 Dual pipeline with Slave enabled
141 --------------------------------
142
143 .. kernel-render:: DOT
144 :alt: Slave pipeline digraph
145 :caption: Slave pipeline enabled data flow
146
147 digraph slave_ppl {
148 rankdir=LR;
149
150 subgraph {
151 "Memory";
152 "Monitor";
153 }
154 node [shape=box]
155 subgraph cluster_pipeline_slave {
156 style=dashed
157 label="Slave Pipeline_B"
158 node [shape=box]
159 {
160 node [bgcolor=grey style=dashed]
161 "Slave.Scaler-0";
162 "Slave.Scaler-1";
163 }
164
165 node [bgcolor=grey style=filled]
166 "Slave.Layer-0" -> "Slave.Scaler-0"
167 "Slave.Layer-1" -> "Slave.Scaler-0"
168 "Slave.Layer-2" -> "Slave.Scaler-1"
169 "Slave.Layer-3" -> "Slave.Scaler-1"
170
171 "Slave.Layer-0" -> "Slave.Compiz"
172 "Slave.Layer-1" -> "Slave.Compiz"
173 "Slave.Layer-2" -> "Slave.Compiz"
174 "Slave.Layer-3" -> "Slave.Compiz"
175 "Slave.Scaler-0" -> "Slave.Compiz"
176 "Slave.Scaler-1" -> "Slave.Compiz"
177 }
178
179 subgraph cluster_pipeline_master {
180 style=dashed
181 label="Master Pipeline_A"
182 node [shape=box]
183 {
184 node [bgcolor=grey style=dashed]
185 "Scaler-0";
186 "Scaler-1";
187 "Scaler-0/1"
188 }
189
190 node [bgcolor=grey style=filled]
191 "Layer-0" -> "Scaler-0"
192 "Layer-1" -> "Scaler-0"
193 "Layer-2" -> "Scaler-1"
194 "Layer-3" -> "Scaler-1"
195
196 "Slave.Compiz" -> "Compiz"
197 "Layer-0" -> "Compiz"
198 "Layer-1" -> "Compiz"
199 "Layer-2" -> "Compiz"
200 "Layer-3" -> "Compiz"
201 "Scaler-0" -> "Compiz"
202 "Scaler-1" -> "Compiz"
203
204 "Compiz" -> "Scaler-0/1" -> "Wb_layer
205 "Compiz" -> "Improc" -> "Timing Contr
206 }
207
208 "Wb_layer" -> "Memory"
209 "Timing Controller" -> "Monitor"
210 }
211
212 Sub-pipelines for input and output
213 ----------------------------------
214
215 A complete display pipeline can be easily divi
216 according to the in/out usage.
217
218 Layer(input) pipeline
219 ~~~~~~~~~~~~~~~~~~~~~
220
221 .. kernel-render:: DOT
222 :alt: Layer data digraph
223 :caption: Layer (input) data flow
224
225 digraph layer_data_flow {
226 rankdir=LR;
227 node [shape=box]
228
229 {
230 node [bgcolor=grey style=dashed]
231 "Scaler-n";
232 }
233
234 "Layer-n" -> "Scaler-n" -> "Compiz"
235 }
236
237 .. kernel-render:: DOT
238 :alt: Layer Split digraph
239 :caption: Layer Split pipeline
240
241 digraph layer_data_flow {
242 rankdir=LR;
243 node [shape=box]
244
245 "Layer-0/1" -> "Scaler-0" -> "Merger"
246 "Layer-2/3" -> "Scaler-1" -> "Merger"
247 "Merger" -> "Compiz"
248 }
249
250 Writeback(output) pipeline
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~
252 .. kernel-render:: DOT
253 :alt: writeback digraph
254 :caption: Writeback(output) data flow
255
256 digraph writeback_data_flow {
257 rankdir=LR;
258 node [shape=box]
259
260 {
261 node [bgcolor=grey style=dashed]
262 "Scaler-n";
263 }
264
265 "Compiz" -> "Scaler-n" -> "Wb_layer"
266 }
267
268 .. kernel-render:: DOT
269 :alt: split writeback digraph
270 :caption: Writeback(output) Split data flow
271
272 digraph writeback_data_flow {
273 rankdir=LR;
274 node [shape=box]
275
276 "Compiz" -> "Splitter"
277 "Splitter" -> "Scaler-0" -> "Merger"
278 "Splitter" -> "Scaler-1" -> "Merger"
279 "Merger" -> "Wb_layer"
280 }
281
282 Display output pipeline
283 ~~~~~~~~~~~~~~~~~~~~~~~
284 .. kernel-render:: DOT
285 :alt: display digraph
286 :caption: display output data flow
287
288 digraph single_ppl {
289 rankdir=LR;
290 node [shape=box]
291
292 "Compiz" -> "Improc" -> "Timing Controll
293 }
294
295 In the following section we'll see these three
296 by KMS-plane/wb_conn/crtc respectively.
297
298 Komeda Resource abstraction
299 ===========================
300
301 struct komeda_pipeline/component
302 --------------------------------
303
304 To fully utilize and easily access/configure t
305 a similar architecture: Pipeline/Component to
306 capabilities, and a specific component include
307
308 - Data flow controlling.
309 - Specific component capabilities and feature
310
311 So the driver defines a common header struct k
312 data flow control and all specific components
313 structure.
314
315 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
316 :internal:
317
318 Resource discovery and initialization
319 =====================================
320
321 Pipeline and component are used to describe ho
322 still need a @struct komeda_dev to describe th
323 the control-abilites of device.
324
325 We have &komeda_dev, &komeda_pipeline, &komeda
326 pipelines. Since komeda is not for D71 only bu
327 of course we’d better share as much as possi
328 achieve this, split the komeda device into two
329
330 - CORE: for common features and capabilities
331 - CHIP: for register programming and HW spec
332
333 CORE can access CHIP by three chip function st
334
335 - struct komeda_dev_funcs
336 - struct komeda_pipeline_funcs
337 - struct komeda_component_funcs
338
339 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
340 :internal:
341
342 Format handling
343 ===============
344
345 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
346 :internal:
347 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
348 :internal:
349
350 Attach komeda_dev to DRM-KMS
351 ============================
352
353 Komeda abstracts resources by pipeline/compone
354 crtc/plane/connector. One KMS-obj cannot repre
355 since the requirements of a single KMS object
356 single component, usually that needs multiple
357 Like set mode, gamma, ctm for KMS all target o
358 compiz, improc and timing_ctrlr to work togeth
359 And a KMS-Plane may require multiple komeda re
360
361 So, one KMS-Obj represents a sub-pipeline of k
362
363 - Plane: `Layer(input) pipeline`_
364 - Wb_connector: `Writeback(output) pipeline`
365 - Crtc: `Display output pipeline`_
366
367 So, for komeda, we treat KMS crtc/plane/connec
368 component, and at any one time a pipeline/comp
369 user. And pipeline/component will be treated a
370 state will be managed by drm_atomic_state as w
371
372 How to map plane to Layer(input) pipeline
373 -----------------------------------------
374
375 Komeda has multiple Layer input pipelines, see
376 - `Single pipeline data flow`_
377 - `Dual pipeline with Slave enabled`_
378
379 The easiest way is binding a plane to a fixed
380 komeda capabilities:
381
382 - Layer Split, See `Layer(input) pipeline`_
383
384 Layer_Split is quite complicated feature,
385 parts and handles it by two layers and two
386 imports an edge problem or effect in the m
387 To avoid such a problem, it needs a compli
388 special configurations to the layer and sc
389 related complexity to user mode.
390
391 - Slave pipeline, See `Dual pipeline with Sl
392
393 Since the compiz component doesn't output
394 only can be used for bottom layers composi
395 hide this limitation to the user. The way
396 Layer according to plane_state->zpos.
397
398 So for komeda, the KMS-plane doesn't represent
399 but multiple Layers with same capabilities. Ko
400 Layers to fit the requirement of one KMS-plane
401
402 Make component/pipeline to be drm_private_obj
403 ---------------------------------------------
404
405 Add :c:type:`drm_private_obj` to :c:type:`kome
406
407 .. code-block:: c
408
409 struct komeda_component {
410 struct drm_private_obj obj;
411 ...
412 }
413
414 struct komeda_pipeline {
415 struct drm_private_obj obj;
416 ...
417 }
418
419 Tracking component_state/pipeline_state by drm
420 ----------------------------------------------
421
422 Add :c:type:`drm_private_state` and user to :c
423 :c:type:`komeda_pipeline_state`
424
425 .. code-block:: c
426
427 struct komeda_component_state {
428 struct drm_private_state obj;
429 void *binding_user;
430 ...
431 }
432
433 struct komeda_pipeline_state {
434 struct drm_private_state obj;
435 struct drm_crtc *crtc;
436 ...
437 }
438
439 komeda component validation
440 ---------------------------
441
442 Komeda has multiple types of components, but t
443 similar, usually including the following steps
444
445 .. code-block:: c
446
447 int komeda_xxxx_validate(struct komeda_com
448 struct komeda_component_output
449 struct drm_plane/crtc/connecto
450 struct drm_plane/crtc/connecto
451 {
452 setup 1: check if component is needed
453 on the user_state; if unneed
454 put the data flow into next
455 Setup 2: check user_state with compon
456 if requirements can be met;
457 Setup 3: get component_state from drm
458 user to component; fail if c
459 user already.
460 Setup 3: configure the component_stat
461 convert user_state to compon
462 Setup 4: adjust the input_dflow and p
463 }
464
465 komeda_kms Abstraction
466 ----------------------
467
468 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
469 :internal:
470
471 komde_kms Functions
472 -------------------
473 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
474 :internal:
475 .. kernel-doc:: drivers/gpu/drm/arm/display/ko
476 :internal:
477
478 Build komeda to be a Linux module driver
479 ========================================
480
481 Now we have two level devices:
482
483 - komeda_dev: describes the real display har
484 - komeda_kms_dev: attaches or connects komed
485
486 All komeda operations are supplied or operated
487 the module driver is only a simple wrapper to
488 (probe/remove/pm) into komeda_dev or komeda_km
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.