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