1========================= 2Kernel Mode Setting (KMS) 3========================= 4 5Drivers must initialize the mode setting core by calling 6:c:func:`drm_mode_config_init()` on the DRM device. The function 7initializes the :c:type:`struct drm_device <drm_device>` 8mode_config field and never fails. Once done, mode configuration must 9be 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 18Mode Configuration 19 20KMS 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 29Modeset 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 38Atomic 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 47CRTC 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 56Frame Buffer Abstraction 57======================== 58 59.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 60 :doc: overview 61 62Frame 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 71DRM 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 80Dumb Buffer Objects 81=================== 82 83.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 84 :doc: overview 85 86Plane Abstraction 87================= 88 89.. kernel-doc:: drivers/gpu/drm/drm_plane.c 90 :doc: overview 91 92Plane 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 101Display 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 110Connector Abstraction 111===================== 112 113.. kernel-doc:: drivers/gpu/drm/drm_connector.c 114 :doc: overview 115 116Connector 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 125Encoder Abstraction 126=================== 127 128.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 129 :doc: overview 130 131Encoder 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 140KMS Initialization and Cleanup 141============================== 142 143A KMS device is abstracted and exposed as a set of planes, CRTCs, 144encoders and connectors. KMS drivers must thus create and initialize all 145those objects at load time after initializing mode setting. 146 147CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 148-------------------------------------------- 149 150A CRTC is an abstraction representing a part of the chip that contains a 151pointer to a scanout buffer. Therefore, the number of CRTCs available 152determines how many independent scanout buffers can be active at any 153given time. The CRTC structure contains several fields to support this: 154a pointer to some video memory (abstracted as a frame buffer object), a 155display mode, and an (x, y) offset into the video memory to support 156panning or configurations where one piece of video memory spans multiple 157CRTCs. 158 159CRTC Initialization 160~~~~~~~~~~~~~~~~~~~ 161 162A KMS device must create and register at least one struct 163:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 164allocated and zeroed by the driver, possibly as part of a larger 165structure, and registered with a call to :c:func:`drm_crtc_init()` 166with a pointer to CRTC functions. 167 168 169Cleanup 170------- 171 172The DRM core manages its objects' lifetime. When an object is not needed 173anymore the core calls its destroy function, which must clean up and 174free 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 181have 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 185Connectors state change detection must be cleanup up with a call to 186:c:func:`drm_kms_helper_poll_fini()`. 187 188Output 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 230In the example above (taken from the i915 driver), a CRTC, connector and 231encoder combination is created. A device-specific i2c bus is also 232created for fetching EDID data and performing monitor detection. Once 233the process is complete, the new connector is registered with sysfs to 234make its properties available to applications. 235 236KMS 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 248KMS Properties 249============== 250 251Property 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 263Standard Connector Properties 264----------------------------- 265 266.. kernel-doc:: drivers/gpu/drm/drm_connector.c 267 :doc: standard connector properties 268 269Plane 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 278Color 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 290Tile Group Property 291------------------- 292 293.. kernel-doc:: drivers/gpu/drm/drm_connector.c 294 :doc: Tile group 295 296Explicit Fencing Properties 297--------------------------- 298 299.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 300 :doc: explicit fencing properties 301 302Existing KMS Properties 303----------------------- 304 305The following table gives description of drm properties exposed by 306various modules/drivers. 307 308.. csv-table:: 309 :header-rows: 1 310 :file: kms-properties.csv 311 312Vertical Blanking 313================= 314 315Vertical blanking plays a major role in graphics rendering. To achieve 316tear-free display, users must synchronize page flips and/or rendering to 317vertical blanking. The DRM API offers ioctls to perform page flips 318synchronized to vertical blanking and wait for vertical blanking. 319 320The DRM core handles most of the vertical blanking management logic, 321which involves filtering out spurious interrupts, keeping race-free 322blanking counters, coping with counter wrap-around and resets and 323keeping use counts. It relies on the driver to generate vertical 324blanking interrupts and optionally provide a hardware vertical blanking 325counter. 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 338Drivers must initialize the vertical blanking handling core with a call 339to :c:func:`drm_vblank_init()` in their load operation. 340 341Vertical blanking interrupts can be enabled by the DRM core or by 342drivers themselves (for instance to handle page flipping operations). 343The DRM core maintains a vertical blanking use count to ensure that the 344interrupts are not disabled while a user still needs them. To increment 345the use count, drivers call :c:func:`drm_vblank_get()`. Upon 346return vertical blanking interrupts are guaranteed to be enabled. 347 348To decrement the use count drivers call 349:c:func:`drm_vblank_put()`. Only when the use count drops to zero 350will the DRM core disable the vertical blanking interrupts after a delay 351by scheduling a timer. The delay is accessible through the 352vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global 353variable and expressed in milliseconds. Its default value is 5000 ms. 354Zero means never disable, and a negative value means disable 355immediately. Drivers may override the behaviour by setting the 356:c:type:`struct drm_device <drm_device>` 357vblank_disable_immediate flag, which when set causes vblank interrupts 358to be disabled immediately regardless of the drm_vblank_offdelay 359value. The flag should only be set if there's a properly working 360hardware vblank counter present. 361 362When a vertical blanking interrupt occurs drivers only need to call the 363:c:func:`drm_handle_vblank()` function to account for the 364interrupt. 365 366Resources allocated by :c:func:`drm_vblank_init()` must be freed 367with a call to :c:func:`drm_vblank_cleanup()` in the driver unload 368operation handler. 369 370Vertical 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: 378