Documentation/gpu/drm-kms.rst

   1 =========================
   2 Kernel Mode Setting (KMS)
   3 =========================
   4
   5 Drivers must initialize the mode setting core by calling
   6 :c:func:`drm_mode_config_init()` on the DRM device. The function
   7 initializes the :c:type:`struct drm_device <drm_device>`
   8 mode_config field and never fails. Once done, mode configuration must
   9 be setup by initializing the following fields.
  10
  11 -  int min_width, min_height; int max_width, max_height;
  12    Minimum and maximum width and height of the frame buffers in pixel
  13    units.
  14
  15 -  struct drm_mode_config_funcs \*funcs;
  16    Mode setting functions.
  17
  18 Mode Configuration
  19
  20 KMS Core Structures and Functions
  21 =================================
  22
  23 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
  24    :export:
  25
  26 .. kernel-doc:: include/drm/drm_mode_config.h
  27    :internal:
  28
  29 Modeset Base Object Abstraction
  30 ===============================
  31
  32 .. kernel-doc:: include/drm/drm_mode_object.h
  33    :internal:
  34
  35 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
  36    :export:
  37
  38 Atomic Mode Setting Function Reference
  39 ======================================
  40
  41 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
  42    :export:
  43
  44 .. kernel-doc:: include/drm/drm_atomic.h
  45    :internal:
  46
  47 CRTC Abstraction
  48 ================
  49
  50 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
  51    :doc: overview
  52
  53 CRTC Functions Reference
  54 --------------------------------
  55
  56 .. kernel-doc:: include/drm/drm_crtc.h
  57    :internal:
  58
  59 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
  60    :export:
  61
  62 Frame Buffer Abstraction
  63 ========================
  64
  65 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
  66    :doc: overview
  67
  68 Frame Buffer Functions Reference
  69 --------------------------------
  70
  71 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
  72    :export:
  73
  74 .. kernel-doc:: include/drm/drm_framebuffer.h
  75    :internal:
  76
  77 DRM Format Handling
  78 ===================
  79
  80 .. kernel-doc:: include/drm/drm_fourcc.h
  81    :internal:
  82
  83 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
  84    :export:
  85
  86 Dumb Buffer Objects
  87 ===================
  88
  89 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
  90    :doc: overview
  91
  92 Plane Abstraction
  93 =================
  94
  95 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
  96    :doc: overview
  97
  98 Plane Functions Reference
  99 -------------------------
 100
 101 .. kernel-doc:: include/drm/drm_plane.h
 102    :internal:
 103
 104 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 105    :export:
 106
 107 Display Modes Function Reference
 108 ================================
 109
 110 .. kernel-doc:: include/drm/drm_modes.h
 111    :internal:
 112
 113 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 114    :export:
 115
 116 Connector Abstraction
 117 =====================
 118
 119 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 120    :doc: overview
 121
 122 Connector Functions Reference
 123 -----------------------------
 124
 125 .. kernel-doc:: include/drm/drm_connector.h
 126    :internal:
 127
 128 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 129    :export:
 130
 131 Encoder Abstraction
 132 ===================
 133
 134 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 135    :doc: overview
 136
 137 Encoder Functions Reference
 138 ---------------------------
 139
 140 .. kernel-doc:: include/drm/drm_encoder.h
 141    :internal:
 142
 143 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 144    :export:
 145
 146 KMS Initialization and Cleanup
 147 ==============================
 148
 149 A KMS device is abstracted and exposed as a set of planes, CRTCs,
 150 encoders and connectors. KMS drivers must thus create and initialize all
 151 those objects at load time after initializing mode setting.
 152
 153 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
 154 --------------------------------------------
 155
 156 A CRTC is an abstraction representing a part of the chip that contains a
 157 pointer to a scanout buffer. Therefore, the number of CRTCs available
 158 determines how many independent scanout buffers can be active at any
 159 given time. The CRTC structure contains several fields to support this:
 160 a pointer to some video memory (abstracted as a frame buffer object), a
 161 display mode, and an (x, y) offset into the video memory to support
 162 panning or configurations where one piece of video memory spans multiple
 163 CRTCs.
 164
 165 CRTC Initialization
 166 ~~~~~~~~~~~~~~~~~~~
 167
 168 A KMS device must create and register at least one struct
 169 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
 170 allocated and zeroed by the driver, possibly as part of a larger
 171 structure, and registered with a call to :c:func:`drm_crtc_init()`
 172 with a pointer to CRTC functions.
 173
 174
 175 Cleanup
 176 -------
 177
 178 The DRM core manages its objects' lifetime. When an object is not needed
 179 anymore the core calls its destroy function, which must clean up and
 180 free every resource allocated for the object. Every
 181 :c:func:`drm_\*_init()` call must be matched with a corresponding
 182 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
 183 (:c:func:`drm_crtc_cleanup()`), planes
 184 (:c:func:`drm_plane_cleanup()`), encoders
 185 (:c:func:`drm_encoder_cleanup()`) and connectors
 186 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
 187 have been added to sysfs must be removed by a call to
 188 :c:func:`drm_connector_unregister()` before calling
 189 :c:func:`drm_connector_cleanup()`.
 190
 191 Connectors state change detection must be cleanup up with a call to
 192 :c:func:`drm_kms_helper_poll_fini()`.
 193
 194 Output discovery and initialization example
 195 -------------------------------------------
 196
 197 .. code-block:: c
 198
 199     void intel_crt_init(struct drm_device *dev)
 200     {
 201         struct drm_connector *connector;
 202         struct intel_output *intel_output;
 203
 204         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
 205         if (!intel_output)
 206             return;
 207
 208         connector = &intel_output->base;
 209         drm_connector_init(dev, &intel_output->base,
 210                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
 211
 212         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
 213                  DRM_MODE_ENCODER_DAC);
 214
 215         drm_mode_connector_attach_encoder(&intel_output->base,
 216                           &intel_output->enc);
 217
 218         /* Set up the DDC bus. */
 219         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
 220         if (!intel_output->ddc_bus) {
 221             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
 222                    "failed.\n");
 223             return;
 224         }
 225
 226         intel_output->type = INTEL_OUTPUT_ANALOG;
 227         connector->interlace_allowed = 0;
 228         connector->doublescan_allowed = 0;
 229
 230         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
 231         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
 232
 233         drm_connector_register(connector);
 234     }
 235
 236 In the example above (taken from the i915 driver), a CRTC, connector and
 237 encoder combination is created. A device-specific i2c bus is also
 238 created for fetching EDID data and performing monitor detection. Once
 239 the process is complete, the new connector is registered with sysfs to
 240 make its properties available to applications.
 241
 242 KMS Locking
 243 ===========
 244
 245 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 246    :doc: kms locking
 247
 248 .. kernel-doc:: include/drm/drm_modeset_lock.h
 249    :internal:
 250
 251 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 252    :export:
 253
 254 KMS Properties
 255 ==============
 256
 257 Property Types and Blob Property Support
 258 ----------------------------------------
 259
 260 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 261    :doc: overview
 262
 263 .. kernel-doc:: include/drm/drm_property.h
 264    :internal:
 265
 266 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 267    :export:
 268
 269 Standard Connector Properties
 270 -----------------------------
 271
 272 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 273    :doc: standard connector properties
 274
 275 Plane Composition Properties
 276 ----------------------------
 277
 278 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 279    :doc: overview
 280
 281 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 282    :export:
 283
 284 Color Management Properties
 285 ---------------------------
 286
 287 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 288    :doc: overview
 289
 290 .. kernel-doc:: include/drm/drm_color_mgmt.h
 291    :internal:
 292
 293 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 294    :export:
 295
 296 Tile Group Property
 297 -------------------
 298
 299 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 300    :doc: Tile group
 301
 302 Explicit Fencing Properties
 303 ---------------------------
 304
 305 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 306    :doc: explicit fencing properties
 307
 308 Existing KMS Properties
 309 -----------------------
 310
 311 The following table gives description of drm properties exposed by
 312 various modules/drivers.
 313
 314 .. csv-table::
 315    :header-rows: 1
 316    :file: kms-properties.csv
 317
 318 Vertical Blanking
 319 =================
 320
 321 Vertical blanking plays a major role in graphics rendering. To achieve
 322 tear-free display, users must synchronize page flips and/or rendering to
 323 vertical blanking. The DRM API offers ioctls to perform page flips
 324 synchronized to vertical blanking and wait for vertical blanking.
 325
 326 The DRM core handles most of the vertical blanking management logic,
 327 which involves filtering out spurious interrupts, keeping race-free
 328 blanking counters, coping with counter wrap-around and resets and
 329 keeping use counts. It relies on the driver to generate vertical
 330 blanking interrupts and optionally provide a hardware vertical blanking
 331 counter. Drivers must implement the following operations.
 332
 333 -  int (\*enable_vblank) (struct drm_device \*dev, int crtc); void
 334    (\*disable_vblank) (struct drm_device \*dev, int crtc);
 335    Enable or disable vertical blanking interrupts for the given CRTC.
 336
 337 -  u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc);
 338    Retrieve the value of the vertical blanking counter for the given
 339    CRTC. If the hardware maintains a vertical blanking counter its value
 340    should be returned. Otherwise drivers can use the
 341    :c:func:`drm_vblank_count()` helper function to handle this
 342    operation.
 343
 344 Drivers must initialize the vertical blanking handling core with a call
 345 to :c:func:`drm_vblank_init()` in their load operation.
 346
 347 Vertical blanking interrupts can be enabled by the DRM core or by
 348 drivers themselves (for instance to handle page flipping operations).
 349 The DRM core maintains a vertical blanking use count to ensure that the
 350 interrupts are not disabled while a user still needs them. To increment
 351 the use count, drivers call :c:func:`drm_vblank_get()`. Upon
 352 return vertical blanking interrupts are guaranteed to be enabled.
 353
 354 To decrement the use count drivers call
 355 :c:func:`drm_vblank_put()`. Only when the use count drops to zero
 356 will the DRM core disable the vertical blanking interrupts after a delay
 357 by scheduling a timer. The delay is accessible through the
 358 vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
 359 variable and expressed in milliseconds. Its default value is 5000 ms.
 360 Zero means never disable, and a negative value means disable
 361 immediately. Drivers may override the behaviour by setting the
 362 :c:type:`struct drm_device <drm_device>`
 363 vblank_disable_immediate flag, which when set causes vblank interrupts
 364 to be disabled immediately regardless of the drm_vblank_offdelay
 365 value. The flag should only be set if there's a properly working
 366 hardware vblank counter present.
 367
 368 When a vertical blanking interrupt occurs drivers only need to call the
 369 :c:func:`drm_handle_vblank()` function to account for the
 370 interrupt.
 371
 372 Resources allocated by :c:func:`drm_vblank_init()` must be freed
 373 with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
 374 operation handler.
 375
 376 Vertical Blanking and Interrupt Handling Functions Reference
 377 ------------------------------------------------------------
 378
 379 .. kernel-doc:: drivers/gpu/drm/drm_irq.c
 380    :export:
 381
 382 .. kernel-doc:: include/drm/drm_irq.h
 383    :internal: