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