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 311Existing KMS Properties 312----------------------- 313 314The following table gives description of drm properties exposed by 315various modules/drivers. 316 317.. csv-table:: 318 :header-rows: 1 319 :file: kms-properties.csv 320 321Vertical Blanking 322================= 323 324Vertical blanking plays a major role in graphics rendering. To achieve 325tear-free display, users must synchronize page flips and/or rendering to 326vertical blanking. The DRM API offers ioctls to perform page flips 327synchronized to vertical blanking and wait for vertical blanking. 328 329The DRM core handles most of the vertical blanking management logic, 330which involves filtering out spurious interrupts, keeping race-free 331blanking counters, coping with counter wrap-around and resets and 332keeping use counts. It relies on the driver to generate vertical 333blanking interrupts and optionally provide a hardware vertical blanking 334counter. Drivers must implement the following operations. 335 336- int (\*enable_vblank) (struct drm_device \*dev, int crtc); void 337 (\*disable_vblank) (struct drm_device \*dev, int crtc); 338 Enable or disable vertical blanking interrupts for the given CRTC. 339 340- u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); 341 Retrieve the value of the vertical blanking counter for the given 342 CRTC. If the hardware maintains a vertical blanking counter its value 343 should be returned. Otherwise drivers can use the 344 :c:func:`drm_vblank_count()` helper function to handle this 345 operation. 346 347Drivers must initialize the vertical blanking handling core with a call 348to :c:func:`drm_vblank_init()` in their load operation. 349 350Vertical blanking interrupts can be enabled by the DRM core or by 351drivers themselves (for instance to handle page flipping operations). 352The DRM core maintains a vertical blanking use count to ensure that the 353interrupts are not disabled while a user still needs them. To increment 354the use count, drivers call :c:func:`drm_vblank_get()`. Upon 355return vertical blanking interrupts are guaranteed to be enabled. 356 357To decrement the use count drivers call 358:c:func:`drm_vblank_put()`. Only when the use count drops to zero 359will the DRM core disable the vertical blanking interrupts after a delay 360by scheduling a timer. The delay is accessible through the 361vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global 362variable and expressed in milliseconds. Its default value is 5000 ms. 363Zero means never disable, and a negative value means disable 364immediately. Drivers may override the behaviour by setting the 365:c:type:`struct drm_device <drm_device>` 366vblank_disable_immediate flag, which when set causes vblank interrupts 367to be disabled immediately regardless of the drm_vblank_offdelay 368value. The flag should only be set if there's a properly working 369hardware vblank counter present. 370 371When a vertical blanking interrupt occurs drivers only need to call the 372:c:func:`drm_handle_vblank()` function to account for the 373interrupt. 374 375Resources allocated by :c:func:`drm_vblank_init()` must be freed 376with a call to :c:func:`drm_vblank_cleanup()` in the driver unload 377operation handler. 378 379Vertical Blanking and Interrupt Handling Functions Reference 380------------------------------------------------------------ 381 382.. kernel-doc:: drivers/gpu/drm/drm_irq.c 383 :export: 384 385.. kernel-doc:: include/drm/drm_irq.h 386 :internal: 387