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