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