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