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:: include/drm/drm_fb_helper.h
 114    :internal:
 115
 116 .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
 117    :export:
 118
 119 .. kernel-doc:: drivers/gpu/drm/drm_fbdev_generic.c
 120    :export:
 121
 122 format Helper Functions Reference
 123 =================================
 124
 125 .. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
 126    :export:
 127
 128 Framebuffer DMA Helper Functions Reference
 129 ==========================================
 130
 131 .. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
 132    :doc: framebuffer dma helper functions
 133
 134 .. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
 135    :export:
 136
 137 Framebuffer GEM Helper Reference
 138 ================================
 139
 140 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
 141    :doc: overview
 142
 143 .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
 144    :export:
 145
 146 .. _drm_bridges:
 147
 148 Bridges
 149 =======
 150
 151 Overview
 152 --------
 153
 154 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 155    :doc: overview
 156
 157 Display Driver Integration
 158 --------------------------
 159
 160 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 161    :doc: display driver integration
 162
 163 Special Care with MIPI-DSI bridges
 164 ----------------------------------
 165
 166 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 167    :doc: special care dsi
 168
 169 Bridge Operations
 170 -----------------
 171
 172 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 173    :doc: bridge operations
 174
 175 Bridge Connector Helper
 176 -----------------------
 177
 178 .. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
 179    :doc: overview
 180
 181
 182 Bridge Helper Reference
 183 -------------------------
 184
 185 .. kernel-doc:: include/drm/drm_bridge.h
 186    :internal:
 187
 188 .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
 189    :export:
 190
 191 Bridge Connector Helper Reference
 192 ---------------------------------
 193
 194 .. kernel-doc:: drivers/gpu/drm/drm_bridge_connector.c
 195    :export:
 196
 197 Panel-Bridge Helper Reference
 198 -----------------------------
 199
 200 .. kernel-doc:: drivers/gpu/drm/bridge/panel.c
 201    :export:
 202
 203 .. _drm_panel_helper:
 204
 205 Panel Helper Reference
 206 ======================
 207
 208 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
 209    :doc: drm panel
 210
 211 .. kernel-doc:: include/drm/drm_panel.h
 212    :internal:
 213
 214 .. kernel-doc:: drivers/gpu/drm/drm_panel.c
 215    :export:
 216
 217 .. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
 218    :export:
 219
 220 Panel Self Refresh Helper Reference
 221 ===================================
 222
 223 .. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
 224    :doc: overview
 225
 226 .. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
 227    :export:
 228
 229 HDCP Helper Functions Reference
 230 ===============================
 231
 232 .. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
 233    :export:
 234
 235 Display Port Helper Functions Reference
 236 =======================================
 237
 238 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
 239    :doc: dp helpers
 240
 241 .. kernel-doc:: include/drm/display/drm_dp.h
 242    :internal:
 243
 244 .. kernel-doc:: include/drm/display/drm_dp_helper.h
 245    :internal:
 246
 247 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
 248    :export:
 249
 250 Display Port CEC Helper Functions Reference
 251 ===========================================
 252
 253 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
 254    :doc: dp cec helpers
 255
 256 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
 257    :export:
 258
 259 Display Port Dual Mode Adaptor Helper Functions Reference
 260 =========================================================
 261
 262 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
 263    :doc: dp dual mode helpers
 264
 265 .. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
 266    :internal:
 267
 268 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
 269    :export:
 270
 271 Display Port MST Helpers
 272 ========================
 273
 274 Overview
 275 --------
 276
 277 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 278    :doc: dp mst helper
 279
 280 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 281    :doc: Branch device and port refcounting
 282
 283 Functions Reference
 284 -------------------
 285
 286 .. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
 287    :internal:
 288
 289 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 290    :export:
 291
 292 Topology Lifetime Internals
 293 ---------------------------
 294
 295 These functions aren't exported to drivers, but are documented here to help make
 296 the MST topology helpers easier to understand
 297
 298 .. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
 299    :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
 300                drm_dp_mst_topology_put_mstb
 301                drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
 302                drm_dp_mst_topology_put_port
 303                drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc
 304
 305 MIPI DBI Helper Functions Reference
 306 ===================================
 307
 308 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
 309    :doc: overview
 310
 311 .. kernel-doc:: include/drm/drm_mipi_dbi.h
 312    :internal:
 313
 314 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
 315    :export:
 316
 317 MIPI DSI Helper Functions Reference
 318 ===================================
 319
 320 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
 321    :doc: dsi helpers
 322
 323 .. kernel-doc:: include/drm/drm_mipi_dsi.h
 324    :internal:
 325
 326 .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
 327    :export:
 328
 329 Display Stream Compression Helper Functions Reference
 330 =====================================================
 331
 332 .. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
 333    :doc: dsc helpers
 334
 335 .. kernel-doc:: include/drm/display/drm_dsc.h
 336    :internal:
 337
 338 .. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
 339    :export:
 340
 341 Output Probing Helper Functions Reference
 342 =========================================
 343
 344 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
 345    :doc: output probing helper overview
 346
 347 .. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
 348    :export:
 349
 350 EDID Helper Functions Reference
 351 ===============================
 352
 353 .. kernel-doc:: include/drm/drm_edid.h
 354    :internal:
 355
 356 .. kernel-doc:: drivers/gpu/drm/drm_edid.c
 357    :export:
 358
 359 SCDC Helper Functions Reference
 360 ===============================
 361
 362 .. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
 363    :doc: scdc helpers
 364
 365 .. kernel-doc:: include/drm/display/drm_scdc_helper.h
 366    :internal:
 367
 368 .. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
 369    :export:
 370
 371 HDMI Infoframes Helper Reference
 372 ================================
 373
 374 Strictly speaking this is not a DRM helper library but generally useable
 375 by any driver interfacing with HDMI outputs like v4l or alsa drivers.
 376 But it nicely fits into the overall topic of mode setting helper
 377 libraries and hence is also included here.
 378
 379 .. kernel-doc:: include/linux/hdmi.h
 380    :internal:
 381
 382 .. kernel-doc:: drivers/video/hdmi.c
 383    :export:
 384
 385 Rectangle Utilities Reference
 386 =============================
 387
 388 .. kernel-doc:: include/drm/drm_rect.h
 389    :doc: rect utils
 390
 391 .. kernel-doc:: include/drm/drm_rect.h
 392    :internal:
 393
 394 .. kernel-doc:: drivers/gpu/drm/drm_rect.c
 395    :export:
 396
 397 Flip-work Helper Reference
 398 ==========================
 399
 400 .. kernel-doc:: include/drm/drm_flip_work.h
 401    :doc: flip utils
 402
 403 .. kernel-doc:: include/drm/drm_flip_work.h
 404    :internal:
 405
 406 .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
 407    :export:
 408
 409 Auxiliary Modeset Helpers
 410 =========================
 411
 412 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
 413    :doc: aux kms helpers
 414
 415 .. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
 416    :export:
 417
 418 OF/DT Helpers
 419 =============
 420
 421 .. kernel-doc:: drivers/gpu/drm/drm_of.c
 422    :doc: overview
 423
 424 .. kernel-doc:: drivers/gpu/drm/drm_of.c
 425    :export:
 426
 427 Legacy Plane Helper Reference
 428 =============================
 429
 430 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
 431    :doc: overview
 432
 433 .. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
 434    :export:
 435
 436 Legacy CRTC/Modeset Helper Functions Reference
 437 ==============================================
 438
 439 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
 440    :doc: overview
 441
 442 .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
 443    :export:
 444
 445 Privacy-screen class
 446 ====================
 447
 448 .. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
 449    :doc: overview
 450
 451 .. kernel-doc:: include/drm/drm_privacy_screen_driver.h
 452    :internal:
 453
 454 .. kernel-doc:: include/drm/drm_privacy_screen_machine.h
 455    :internal:
 456
 457 .. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
 458    :export: