1.. SPDX-License-Identifier: GPL-2.0
2
3==============================
4 drm/komeda Arm display driver
5==============================
6
7The drm/komeda driver supports the Arm display processor D71 and later products,
8this document gives a brief overview of driver design: how it works and why
9design it like that.
10
11Overview of D71 like display IPs
12================================
13
14From D71, Arm display IP begins to adopt a flexible and modularized
15architecture. A display pipeline is made up of multiple individual and
16functional pipeline stages called components, and every component has some
17specific capabilities that can give the flowed pipeline pixel data a
18particular processing.
19
20Typical D71 components:
21
22Layer
23-----
24Layer is the first pipeline stage, which prepares the pixel data for the next
25stage. It fetches the pixel from memory, decodes it if it's AFBC, rotates the
26source image, unpacks or converts YUV pixels to the device internal RGB pixels,
27then adjusts the color_space of pixels if needed.
28
29Scaler
30------
31As its name suggests, scaler takes responsibility for scaling, and D71 also
32supports image enhancements by scaler.
33The usage of scaler is very flexible and can be connected to layer output
34for layer scaling, or connected to compositor and scale the whole display
35frame and then feed the output data into wb_layer which will then write it
36into memory.
37
38Compositor (compiz)
39-------------------
40Compositor blends multiple layers or pixel data flows into one single display
41frame. its output frame can be fed into post image processor for showing it on
42the monitor or fed into wb_layer and written to memory at the same time.
43user can also insert a scaler between compositor and wb_layer to down scale
44the display frame first and then write to memory.
45
46Writeback Layer (wb_layer)
47--------------------------
48Writeback layer does the opposite things of Layer, which connects to compiz
49and writes the composition result to memory.
50
51Post image processor (improc)
52-----------------------------
53Post image processor adjusts frame data like gamma and color space to fit the
54requirements of the monitor.
55
56Timing controller (timing_ctrlr)
57--------------------------------
58Final stage of display pipeline, Timing controller is not for the pixel
59handling, but only for controlling the display timing.
60
61Merger
62------
63D71 scaler mostly only has the half horizontal input/output capabilities
64compared with Layer, like if Layer supports 4K input size, the scaler only can
65support 2K input/output in the same time. To achieve the ful frame scaling, D71
66introduces Layer Split, which splits the whole image to two half parts and feeds
67them to two Layers A and B, and does the scaling independently. After scaling
68the result need to be fed to merger to merge two part images together, and then
69output merged result to compiz.
70
71Splitter
72--------
73Similar to Layer Split, but Splitter is used for writeback, which splits the
74compiz result to two parts and then feed them to two scalers.
75
76Possible D71 Pipeline usage
77===========================
78
79Benefitting from the modularized architecture, D71 pipelines can be easily
80adjusted to fit different usages. And D71 has two pipelines, which support two
81types of working mode:
82
83-   Dual display mode
84    Two pipelines work independently and separately to drive two display outputs.
85
86-   Single display mode
87    Two pipelines work together to drive only one display output.
88
89    On this mode, pipeline_B doesn't work indenpendently, but outputs its
90    composition result into pipeline_A, and its pixel timing also derived from
91    pipeline_A.timing_ctrlr. The pipeline_B works just like a "slave" of
92    pipeline_A(master)
93
94Single 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 Controller"
134      }
135
136      "Wb_layer" -> "Memory"
137      "Timing Controller" -> "Monitor"
138   }
139
140Dual 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 Controller"
206      }
207
208      "Wb_layer" -> "Memory"
209      "Timing Controller" -> "Monitor"
210   }
211
212Sub-pipelines for input and output
213----------------------------------
214
215A complete display pipeline can be easily divided into three sub-pipelines
216according to the in/out usage.
217
218Layer(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
250Writeback(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
282Display 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 Controller"
293   }
294
295In the following section we'll see these three sub-pipelines will be handled
296by KMS-plane/wb_conn/crtc respectively.
297
298Komeda Resource abstraction
299===========================
300
301struct komeda_pipeline/component
302--------------------------------
303
304To fully utilize and easily access/configure the HW, the driver side also uses
305a similar architecture: Pipeline/Component to describe the HW features and
306capabilities, and a specific component includes two parts:
307
308-  Data flow controlling.
309-  Specific component capabilities and features.
310
311So the driver defines a common header struct komeda_component to describe the
312data flow control and all specific components are a subclass of this base
313structure.
314
315.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h
316   :internal:
317
318Resource discovery and initialization
319=====================================
320
321Pipeline and component are used to describe how to handle the pixel data. We
322still need a @struct komeda_dev to describe the whole view of the device, and
323the control-abilites of device.
324
325We have &komeda_dev, &komeda_pipeline, &komeda_component. Now fill devices with
326pipelines. Since komeda is not for D71 only but also intended for later products,
327of course we’d better share as much as possible between different products. To
328achieve this, split the komeda device into two layers: CORE and CHIP.
329
330-   CORE: for common features and capabilities handling.
331-   CHIP: for register programming and HW specific feature (limitation) handling.
332
333CORE can access CHIP by three chip function structures:
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/komeda/komeda_dev.h
340   :internal:
341
342Format handling
343===============
344
345.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_format_caps.h
346   :internal:
347.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h
348   :internal:
349
350Attach komeda_dev to DRM-KMS
351============================
352
353Komeda abstracts resources by pipeline/component, but DRM-KMS uses
354crtc/plane/connector. One KMS-obj cannot represent only one single component,
355since the requirements of a single KMS object cannot simply be achieved by a
356single component, usually that needs multiple components to fit the requirement.
357Like set mode, gamma, ctm for KMS all target on CRTC-obj, but komeda needs
358compiz, improc and timing_ctrlr to work together to fit these requirements.
359And a KMS-Plane may require multiple komeda resources: layer/scaler/compiz.
360
361So, one KMS-Obj represents a sub-pipeline of komeda resources.
362
363-   Plane: `Layer(input) pipeline`_
364-   Wb_connector: `Writeback(output) pipeline`_
365-   Crtc: `Display output pipeline`_
366
367So, for komeda, we treat KMS crtc/plane/connector as users of pipeline and
368component, and at any one time a pipeline/component only can be used by one
369user. And pipeline/component will be treated as private object of DRM-KMS; the
370state will be managed by drm_atomic_state as well.
371
372How to map plane to Layer(input) pipeline
373-----------------------------------------
374
375Komeda has multiple Layer input pipelines, see:
376-   `Single pipeline data flow`_
377-   `Dual pipeline with Slave enabled`_
378
379The easiest way is binding a plane to a fixed Layer pipeline, but consider the
380komeda capabilities:
381
382-   Layer Split, See `Layer(input) pipeline`_
383
384    Layer_Split is quite complicated feature, which splits a big image into two
385    parts and handles it by two layers and two scalers individually. But it
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 complicated Split calculation and some
388    special configurations to the layer and scaler. We'd better hide such HW
389    related complexity to user mode.
390
391-   Slave pipeline, See `Dual pipeline with Slave enabled`_
392
393    Since the compiz component doesn't output alpha value, the slave pipeline
394    only can be used for bottom layers composition. The komeda driver wants to
395    hide this limitation to the user. The way to do this is to pick a suitable
396    Layer according to plane_state->zpos.
397
398So for komeda, the KMS-plane doesn't represent a fixed komeda layer pipeline,
399but multiple Layers with same capabilities. Komeda will select one or more
400Layers to fit the requirement of one KMS-plane.
401
402Make component/pipeline to be drm_private_obj
403---------------------------------------------
404
405Add :c:type:`drm_private_obj` to :c:type:`komeda_component`, :c:type:`komeda_pipeline`
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
419Tracking component_state/pipeline_state by drm_atomic_state
420-----------------------------------------------------------
421
422Add :c:type:`drm_private_state` and user to :c:type:`komeda_component_state`,
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
439komeda component validation
440---------------------------
441
442Komeda has multiple types of components, but the process of validation are
443similar, usually including the following steps:
444
445.. code-block:: c
446
447    int komeda_xxxx_validate(struct komeda_component_xxx xxx_comp,
448                struct komeda_component_output *input_dflow,
449                struct drm_plane/crtc/connector *user,
450                struct drm_plane/crtc/connector_state, *user_state)
451    {
452         setup 1: check if component is needed, like the scaler is optional depending
453                  on the user_state; if unneeded, just return, and the caller will
454                  put the data flow into next stage.
455         Setup 2: check user_state with component features and capabilities to see
456                  if requirements can be met; if not, return fail.
457         Setup 3: get component_state from drm_atomic_state, and try set to set
458                  user to component; fail if component has been assigned to another
459                  user already.
460         Setup 3: configure the component_state, like set its input component,
461                  convert user_state to component specific state.
462         Setup 4: adjust the input_dflow and prepare it for the next stage.
463    }
464
465komeda_kms Abstraction
466----------------------
467
468.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_kms.h
469   :internal:
470
471komde_kms Functions
472-------------------
473.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_crtc.c
474   :internal:
475.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_plane.c
476   :internal:
477
478Build komeda to be a Linux module driver
479========================================
480
481Now we have two level devices:
482
483-   komeda_dev: describes the real display hardware.
484-   komeda_kms_dev: attaches or connects komeda_dev to DRM-KMS.
485
486All komeda operations are supplied or operated by komeda_dev or komeda_kms_dev,
487the module driver is only a simple wrapper to pass the Linux command
488(probe/remove/pm) into komeda_dev or komeda_kms_dev.
489