komeda-kms.rst 15 KB

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