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:: include/drm/drm_fourcc.h 67 :internal: 68 69.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 70 :export: 71 72Dumb Buffer Objects 73=================== 74 75The KMS API doesn't standardize backing storage object creation and 76leaves it to driver-specific ioctls. Furthermore actually creating a 77buffer object even for GEM-based drivers is done through a 78driver-specific ioctl - GEM only has a common userspace interface for 79sharing and destroying objects. While not an issue for full-fledged 80graphics stacks that include device-specific userspace components (in 81libdrm for instance), this limit makes DRM-based early boot graphics 82unnecessarily complex. 83 84Dumb objects partly alleviate the problem by providing a standard API to 85create dumb buffers suitable for scanout, which can then be used to 86create KMS frame buffers. 87 88To support dumb objects drivers must implement the dumb_create, 89dumb_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 112Note that dumb objects may not be used for gpu acceleration, as has been 113attempted on some ARM embedded platforms. Such drivers really must have 114a hardware-specific ioctl to allocate suitable buffer objects. 115 116Plane Abstraction 117================= 118 119.. kernel-doc:: drivers/gpu/drm/drm_plane.c 120 :doc: overview 121 122Plane 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 131Display 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 140Connector Abstraction 141===================== 142 143.. kernel-doc:: drivers/gpu/drm/drm_connector.c 144 :doc: overview 145 146Connector 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 155Encoder Abstraction 156=================== 157 158.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 159 :doc: overview 160 161Encoder 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 170KMS Initialization and Cleanup 171============================== 172 173A KMS device is abstracted and exposed as a set of planes, CRTCs, 174encoders and connectors. KMS drivers must thus create and initialize all 175those objects at load time after initializing mode setting. 176 177CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 178-------------------------------------------- 179 180A CRTC is an abstraction representing a part of the chip that contains a 181pointer to a scanout buffer. Therefore, the number of CRTCs available 182determines how many independent scanout buffers can be active at any 183given time. The CRTC structure contains several fields to support this: 184a pointer to some video memory (abstracted as a frame buffer object), a 185display mode, and an (x, y) offset into the video memory to support 186panning or configurations where one piece of video memory spans multiple 187CRTCs. 188 189CRTC Initialization 190~~~~~~~~~~~~~~~~~~~ 191 192A KMS device must create and register at least one struct 193:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 194allocated and zeroed by the driver, possibly as part of a larger 195structure, and registered with a call to :c:func:`drm_crtc_init()` 196with a pointer to CRTC functions. 197 198 199Cleanup 200------- 201 202The DRM core manages its objects' lifetime. When an object is not needed 203anymore the core calls its destroy function, which must clean up and 204free 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 211have 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 215Connectors state change detection must be cleanup up with a call to 216:c:func:`drm_kms_helper_poll_fini()`. 217 218Output 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 260In the example above (taken from the i915 driver), a CRTC, connector and 261encoder combination is created. A device-specific i2c bus is also 262created for fetching EDID data and performing monitor detection. Once 263the process is complete, the new connector is registered with sysfs to 264make its properties available to applications. 265 266KMS 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 278KMS Properties 279============== 280 281Property 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 293Plane 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 302Color 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 314Existing KMS Properties 315----------------------- 316 317The following table gives description of drm properties exposed by 318various modules/drivers. 319 320.. csv-table:: 321 :header-rows: 1 322 :file: kms-properties.csv 323 324Vertical Blanking 325================= 326 327Vertical blanking plays a major role in graphics rendering. To achieve 328tear-free display, users must synchronize page flips and/or rendering to 329vertical blanking. The DRM API offers ioctls to perform page flips 330synchronized to vertical blanking and wait for vertical blanking. 331 332The DRM core handles most of the vertical blanking management logic, 333which involves filtering out spurious interrupts, keeping race-free 334blanking counters, coping with counter wrap-around and resets and 335keeping use counts. It relies on the driver to generate vertical 336blanking interrupts and optionally provide a hardware vertical blanking 337counter. 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 350Drivers must initialize the vertical blanking handling core with a call 351to :c:func:`drm_vblank_init()` in their load operation. 352 353Vertical blanking interrupts can be enabled by the DRM core or by 354drivers themselves (for instance to handle page flipping operations). 355The DRM core maintains a vertical blanking use count to ensure that the 356interrupts are not disabled while a user still needs them. To increment 357the use count, drivers call :c:func:`drm_vblank_get()`. Upon 358return vertical blanking interrupts are guaranteed to be enabled. 359 360To decrement the use count drivers call 361:c:func:`drm_vblank_put()`. Only when the use count drops to zero 362will the DRM core disable the vertical blanking interrupts after a delay 363by scheduling a timer. The delay is accessible through the 364vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global 365variable and expressed in milliseconds. Its default value is 5000 ms. 366Zero means never disable, and a negative value means disable 367immediately. Drivers may override the behaviour by setting the 368:c:type:`struct drm_device <drm_device>` 369vblank_disable_immediate flag, which when set causes vblank interrupts 370to be disabled immediately regardless of the drm_vblank_offdelay 371value. The flag should only be set if there's a properly working 372hardware vblank counter present. 373 374When a vertical blanking interrupt occurs drivers only need to call the 375:c:func:`drm_handle_vblank()` function to account for the 376interrupt. 377 378Resources allocated by :c:func:`drm_vblank_init()` must be freed 379with a call to :c:func:`drm_vblank_cleanup()` in the driver unload 380operation handler. 381 382Vertical 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: 390