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