Documentation/gpu/drm-kms-helpers.rst

   1 =============================
   2 Mode Setting Helper Functions
   3 =============================
   4
   5 The DRM subsystem aims for a strong separation between core code and helper
   6 libraries. Core code takes care of general setup and teardown and decoding
   7 userspace requests to kernel internal objects. Everything else is handled by a
   8 large set of helper libraries, which can be combined freely to pick and choose
   9 for each driver what fits, and avoid shared code where special behaviour is
  10 needed.
  11
  12 This distinction between core code and helpers is especially strong in the
  13 modesetting code, where there's a shared userspace ABI for all drivers. This is
  14 in contrast to the render side, where pretty much everything (with very few
  15 exceptions) can be considered optional helper code.
  16
  17 There are a few areas these helpers can grouped into:
  18
  19 * Helpers to implement modesetting. The important ones here are the atomic
  20   helpers. Old drivers still often use the legacy CRTC helpers. They both share
  21   the same set of common helper vtables. For really simple drivers (anything
  22   that would have been a great fit in the deprecated fbdev subsystem) there's
  23   also the simple display pipe helpers.
  24
  25 * There's a big pile of helpers for handling outputs. First the generic bridge
  26   helpers for handling encoder and transcoder IP blocks. Second the panel helpers
  27   for handling panel-related information and logic. Plus then a big set of
  28   helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
  29   there's also generic helpers for handling output probing, and for dealing with
  30   EDIDs.
  31
  32 * The last group of helpers concerns itself with the frontend side of a display
  33   pipeline: Planes, handling rectangles for visibility checking and scissoring,
  34   flip queues and assorted bits.
  35
  36 Modeset Helper Reference for Common Vtables
  37 ===========================================
  38
  39 .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
  40    :doc: overview
  41
  42 .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
  43    :internal:
  44
  45 .. _drm_atomic_helper:
  46
  47 Atomic Modeset Helper Functions Reference
  48 =========================================
  49
  50 Overview
  51 --------
  52
  53 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
  54    :doc: overview
  55
  56 Implementing Asynchronous Atomic Commit
  57 ---------------------------------------
  58
  59 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
  60    :doc: implementing nonblocking commit
  61
  62 Helper Functions Reference
  63 --------------------------
  64
  65 .. kernel-doc:: include/drm/drm_atomic_helper.h
  66    :internal:
  67
  68 .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
  69    :export:
  70
  71 Atomic State Reset and Initialization
  72 -------------------------------------
  73
  74 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
  75    :doc: atomic state reset and initialization
  76
  77 Atomic State Helper Reference
  78 -----------------------------
  79
  80 .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
  81    :export:
  82
  83 GEM Atomic Helper Reference
  84 ---------------------------
  85
  86 .. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
  87    :doc: overview
  88
  89 .. kernel-doc:: include/drm/drm_gem_atomic_helper.h
  90    :internal:
  91
  92 .. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
  93    :export:
  94
  95 Simple KMS Helper Reference
  96 ===========================
  97
  98 .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
  99    :doc: overview
 100
 101 .. kernel-doc:: include/drm/drm_simple_kms_helper.h
 102    :internal:
 103
 104 .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
 105    :export:
 106
 107 fbdev Helper Functions Reference
 108 ================================
 109
 110 .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
 111    :doc: fbdev helpers
 112
 113 .. kernel-doc:: drivers/gpu/drm/drm_fbdev_dma.c
 114    :export:
 115
 116 .. kernel-doc:: drivers/gpu/drm/drm_fbdev_shmem.c
 117    :export:
 118
 119 .. kernel-doc:: drivers/gpu/drm/drm_fbdev_ttm.c
 120    :export:
 121
 122 .. kernel-doc:: include/drm/drm_fb_helper.h
 123    :internal:
 124
 125 .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
 126    :export:
 127
 128 format Helper Functions Reference
 129 =================================
 130
 131 .. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
 132    :export:
 133
 134 Framebuffer DMA Helper Functions Reference
 135 ==========================================
 136
 137 .. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
 138    :doc: framebuffer dma helper functions
 139
 140 .. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
 141    :export:
 142
 143 Framebuffer GEM Helper Reference
 144 ================================
 145
 146 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
 147    :doc: overview
 148
 149 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
 150    :export:
 151
 152 .. _drm_bridges:
 153
 154 Bridges
 155 =======
 156
 157 Overview
 158 --------
 159
 160 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 161    :doc: overview
 162
 163 Display Driver Integration
 164 --------------------------
 165
 166 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 167    :doc: display driver integration
 168
 169 Special Care with MIPI-DSI bridges
 170 ----------------------------------
 171
 172 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 173    :doc: special care dsi
 174
 175 Bridge Operations
 176 -----------------
 177
 178 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 179    :doc: bridge operations
 180
 181 Bridge Connector Helper
 182 -----------------------
 183
 184 .. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
 185    :doc: overview
 186
 187
 188 Bridge Helper Reference
 189 -------------------------
 190
 191 .. kernel-doc:: include/drm/drm_bridge.h
 192    :internal:
 193
 194 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 195    :export:
 196
 197 MIPI-DSI bridge operation
 198 -------------------------
 199
 200 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 201    :doc: dsi bridge operations
 202
 203
 204 Bridge Connector Helper Reference
 205 ---------------------------------
 206
 207 .. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
 208    :export:
 209
 210 Panel-Bridge Helper Reference
 211 -----------------------------
 212
 213 .. kernel-doc:: drivers/gpu/drm/bridge/panel.c
 214    :export:
 215
 216 .. _drm_panel_helper:
 217
 218 Panel Helper Reference
 219 ======================
 220
 221 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
 222    :doc: drm panel
 223
 224 .. kernel-doc:: include/drm/drm_panel.h
 225    :internal:
 226
 227 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
 228    :export:
 229
 230 .. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
 231    :export:
 232
 233 Panel Self Refresh Helper Reference
 234 ===================================
 235
 236 .. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
 237    :doc: overview
 238
 239 .. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
 240    :export:
 241
 242 HDCP Helper Functions Reference
 243 ===============================
 244
 245 .. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
 246    :export:
 247
 248 Display Port Helper Functions Reference
 249 =======================================
 250
 251 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
 252    :doc: dp helpers
 253
 254 .. kernel-doc:: include/drm/display/drm_dp.h
 255    :internal:
 256
 257 .. kernel-doc:: include/drm/display/drm_dp_helper.h
 258    :internal:
 259
 260 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
 261    :export:
 262
 263 Display Port CEC Helper Functions Reference
 264 ===========================================
 265
 266 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
 267    :doc: dp cec helpers
 268
 269 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
 270    :export:
 271
 272 Display Port Dual Mode Adaptor Helper Functions Reference
 273 =========================================================
 274
 275 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
 276    :doc: dp dual mode helpers
 277
 278 .. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
 279    :internal:
 280
 281 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
 282    :export:
 283
 284 Display Port MST Helpers
 285 ========================
 286
 287 Overview
 288 --------
 289
 290 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 291    :doc: dp mst helper
 292
 293 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 294    :doc: Branch device and port refcounting
 295
 296 Functions Reference
 297 -------------------
 298
 299 .. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
 300    :internal:
 301
 302 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 303    :export:
 304
 305 Topology Lifetime Internals
 306 ---------------------------
 307
 308 These functions aren't exported to drivers, but are documented here to help make
 309 the MST topology helpers easier to understand
 310
 311 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 312    :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
 313                drm_dp_mst_topology_put_mstb
 314                drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
 315                drm_dp_mst_topology_put_port
 316                drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
 317
 318 MIPI DBI Helper Functions Reference
 319 ===================================
 320
 321 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
 322    :doc: overview
 323
 324 .. kernel-doc:: include/drm/drm_mipi_dbi.h
 325    :internal:
 326
 327 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
 328    :export:
 329
 330 MIPI DSI Helper Functions Reference
 331 ===================================
 332
 333 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
 334    :doc: dsi helpers
 335
 336 .. kernel-doc:: include/drm/drm_mipi_dsi.h
 337    :internal:
 338
 339 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
 340    :export:
 341
 342 Display Stream Compression Helper Functions Reference
 343 =====================================================
 344
 345 .. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
 346    :doc: dsc helpers
 347
 348 .. kernel-doc:: include/drm/display/drm_dsc.h
 349    :internal:
 350
 351 .. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
 352    :export:
 353
 354 Output Probing Helper Functions Reference
 355 =========================================
 356
 357 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
 358    :doc: output probing helper overview
 359
 360 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
 361    :export:
 362
 363 EDID Helper Functions Reference
 364 ===============================
 365
 366 .. kernel-doc:: include/drm/drm_edid.h
 367    :internal:
 368
 369 .. kernel-doc:: drivers/gpu/drm/drm_edid.c
 370    :export:
 371
 372 .. kernel-doc:: include/drm/drm_eld.h
 373    :internal:
 374
 375 .. kernel-doc:: drivers/gpu/drm/drm_eld.c
 376    :export:
 377
 378 SCDC Helper Functions Reference
 379 ===============================
 380
 381 .. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
 382    :doc: scdc helpers
 383
 384 .. kernel-doc:: include/drm/display/drm_scdc_helper.h
 385    :internal:
 386
 387 .. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
 388    :export:
 389
 390 HDMI Infoframes Helper Reference
 391 ================================
 392
 393 Strictly speaking this is not a DRM helper library but generally usable
 394 by any driver interfacing with HDMI outputs like v4l or alsa drivers.
 395 But it nicely fits into the overall topic of mode setting helper
 396 libraries and hence is also included here.
 397
 398 .. kernel-doc:: include/linux/hdmi.h
 399    :internal:
 400
 401 .. kernel-doc:: drivers/video/hdmi.c
 402    :export:
 403
 404 Rectangle Utilities Reference
 405 =============================
 406
 407 .. kernel-doc:: include/drm/drm_rect.h
 408    :doc: rect utils
 409
 410 .. kernel-doc:: include/drm/drm_rect.h
 411    :internal:
 412
 413 .. kernel-doc:: drivers/gpu/drm/drm_rect.c
 414    :export:
 415
 416 Flip-work Helper Reference
 417 ==========================
 418
 419 .. kernel-doc:: include/drm/drm_flip_work.h
 420    :doc: flip utils
 421
 422 .. kernel-doc:: include/drm/drm_flip_work.h
 423    :internal:
 424
 425 .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
 426    :export:
 427
 428 Auxiliary Modeset Helpers
 429 =========================
 430
 431 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
 432    :doc: aux kms helpers
 433
 434 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
 435    :export:
 436
 437 OF/DT Helpers
 438 =============
 439
 440 .. kernel-doc:: drivers/gpu/drm/drm_of.c
 441    :doc: overview
 442
 443 .. kernel-doc:: drivers/gpu/drm/drm_of.c
 444    :export:
 445
 446 Legacy Plane Helper Reference
 447 =============================
 448
 449 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
 450    :doc: overview
 451
 452 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
 453    :export:
 454
 455 Legacy CRTC/Modeset Helper Functions Reference
 456 ==============================================
 457
 458 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
 459    :doc: overview
 460
 461 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
 462    :export:
 463
 464 Privacy-screen class
 465 ====================
 466
 467 .. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
 468    :doc: overview
 469
 470 .. kernel-doc:: include/drm/drm_privacy_screen_driver.h
 471    :internal:
 472
 473 .. kernel-doc:: include/drm/drm_privacy_screen_machine.h
 474    :internal:
 475
 476 .. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
 477    :export: