komeda-kms.rst (15549B)
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 programing 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: attachs 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.