1============= 2DRM Internals 3============= 4 5This chapter documents DRM internals relevant to driver authors and 6developers working to add support for the latest features to existing 7drivers. 8 9First, we go over some typical driver initialization requirements, like 10setting up command buffers, creating an initial output configuration, 11and initializing core services. Subsequent sections cover core internals 12in more detail, providing implementation notes and examples. 13 14The DRM layer provides several services to graphics drivers, many of 15them driven by the application interfaces it provides through libdrm, 16the library that wraps most of the DRM ioctls. These include vblank 17event handling, memory management, output management, framebuffer 18management, command submission & fencing, suspend/resume support, and 19DMA services. 20 21Driver Initialization 22===================== 23 24At the core of every DRM driver is a :c:type:`struct drm_driver 25<drm_driver>` structure. Drivers typically statically initialize 26a drm_driver structure, and then pass it to 27:c:func:`drm_dev_alloc()` to allocate a device instance. After the 28device instance is fully initialized it can be registered (which makes 29it accessible from userspace) using :c:func:`drm_dev_register()`. 30 31The :c:type:`struct drm_driver <drm_driver>` structure 32contains static information that describes the driver and features it 33supports, and pointers to methods that the DRM core will call to 34implement the DRM API. We will first go through the :c:type:`struct 35drm_driver <drm_driver>` static information fields, and will 36then describe individual operations in details as they get used in later 37sections. 38 39Driver Information 40------------------ 41 42Driver Features 43~~~~~~~~~~~~~~~ 44 45Drivers inform the DRM core about their requirements and supported 46features by setting appropriate flags in the driver_features field. 47Since those flags influence the DRM core behaviour since registration 48time, most of them must be set to registering the :c:type:`struct 49drm_driver <drm_driver>` instance. 50 51u32 driver_features; 52 53DRIVER_USE_AGP 54 Driver uses AGP interface, the DRM core will manage AGP resources. 55 56DRIVER_LEGACY 57 Denote a legacy driver using shadow attach. Don't use. 58 59DRIVER_KMS_LEGACY_CONTEXT 60 Used only by nouveau for backwards compatibility with existing userspace. 61 Don't use. 62 63DRIVER_PCI_DMA 64 Driver is capable of PCI DMA, mapping of PCI DMA buffers to 65 userspace will be enabled. Deprecated. 66 67DRIVER_SG 68 Driver can perform scatter/gather DMA, allocation and mapping of 69 scatter/gather buffers will be enabled. Deprecated. 70 71DRIVER_HAVE_DMA 72 Driver supports DMA, the userspace DMA API will be supported. 73 Deprecated. 74 75DRIVER_HAVE_IRQ; DRIVER_IRQ_SHARED 76 DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler 77 managed by the DRM Core. The core will support simple IRQ handler 78 installation when the flag is set. The installation process is 79 described in ?. 80 81 DRIVER_IRQ_SHARED indicates whether the device & handler support 82 shared IRQs (note that this is required of PCI drivers). 83 84DRIVER_GEM 85 Driver use the GEM memory manager. 86 87DRIVER_MODESET 88 Driver supports mode setting interfaces (KMS). 89 90DRIVER_PRIME 91 Driver implements DRM PRIME buffer sharing. 92 93DRIVER_RENDER 94 Driver supports dedicated render nodes. 95 96DRIVER_ATOMIC 97 Driver supports atomic properties. In this case the driver must 98 implement appropriate obj->atomic_get_property() vfuncs for any 99 modeset objects with driver specific properties. 100 101Major, Minor and Patchlevel 102~~~~~~~~~~~~~~~~~~~~~~~~~~~ 103 104int major; int minor; int patchlevel; 105The DRM core identifies driver versions by a major, minor and patch 106level triplet. The information is printed to the kernel log at 107initialization time and passed to userspace through the 108DRM_IOCTL_VERSION ioctl. 109 110The major and minor numbers are also used to verify the requested driver 111API version passed to DRM_IOCTL_SET_VERSION. When the driver API 112changes between minor versions, applications can call 113DRM_IOCTL_SET_VERSION to select a specific version of the API. If the 114requested major isn't equal to the driver major, or the requested minor 115is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will 116return an error. Otherwise the driver's set_version() method will be 117called with the requested version. 118 119Name, Description and Date 120~~~~~~~~~~~~~~~~~~~~~~~~~~ 121 122char \*name; char \*desc; char \*date; 123The driver name is printed to the kernel log at initialization time, 124used for IRQ registration and passed to userspace through 125DRM_IOCTL_VERSION. 126 127The driver description is a purely informative string passed to 128userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by 129the kernel. 130 131The driver date, formatted as YYYYMMDD, is meant to identify the date of 132the latest modification to the driver. However, as most drivers fail to 133update it, its value is mostly useless. The DRM core prints it to the 134kernel log at initialization time and passes it to userspace through the 135DRM_IOCTL_VERSION ioctl. 136 137Device Instance and Driver Handling 138----------------------------------- 139 140.. kernel-doc:: drivers/gpu/drm/drm_drv.c 141 :doc: driver instance overview 142 143.. kernel-doc:: drivers/gpu/drm/drm_drv.c 144 :export: 145 146Driver Load 147----------- 148 149IRQ Registration 150~~~~~~~~~~~~~~~~ 151 152The DRM core tries to facilitate IRQ handler registration and 153unregistration by providing :c:func:`drm_irq_install()` and 154:c:func:`drm_irq_uninstall()` functions. Those functions only 155support a single interrupt per device, devices that use more than one 156IRQs need to be handled manually. 157 158Managed IRQ Registration 159'''''''''''''''''''''''' 160 161:c:func:`drm_irq_install()` starts by calling the irq_preinstall 162driver operation. The operation is optional and must make sure that the 163interrupt will not get fired by clearing all pending interrupt flags or 164disabling the interrupt. 165 166The passed-in IRQ will then be requested by a call to 167:c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature 168flag is set, a shared (IRQF_SHARED) IRQ handler will be requested. 169 170The IRQ handler function must be provided as the mandatory irq_handler 171driver operation. It will get passed directly to 172:c:func:`request_irq()` and thus has the same prototype as all IRQ 173handlers. It will get called with a pointer to the DRM device as the 174second argument. 175 176Finally the function calls the optional irq_postinstall driver 177operation. The operation usually enables interrupts (excluding the 178vblank interrupt, which is enabled separately), but drivers may choose 179to enable/disable interrupts at a different time. 180 181:c:func:`drm_irq_uninstall()` is similarly used to uninstall an 182IRQ handler. It starts by waking up all processes waiting on a vblank 183interrupt to make sure they don't hang, and then calls the optional 184irq_uninstall driver operation. The operation must disable all hardware 185interrupts. Finally the function frees the IRQ by calling 186:c:func:`free_irq()`. 187 188Manual IRQ Registration 189''''''''''''''''''''''' 190 191Drivers that require multiple interrupt handlers can't use the managed 192IRQ registration functions. In that case IRQs must be registered and 193unregistered manually (usually with the :c:func:`request_irq()` and 194:c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and 195:c:func:`devm_free_irq()` equivalents). 196 197When manually registering IRQs, drivers must not set the 198DRIVER_HAVE_IRQ driver feature flag, and must not provide the 199irq_handler driver operation. They must set the :c:type:`struct 200drm_device <drm_device>` irq_enabled field to 1 upon 201registration of the IRQs, and clear it to 0 after unregistering the 202IRQs. 203 204Memory Manager Initialization 205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 206 207Every DRM driver requires a memory manager which must be initialized at 208load time. DRM currently contains two memory managers, the Translation 209Table Manager (TTM) and the Graphics Execution Manager (GEM). This 210document describes the use of the GEM memory manager only. See ? for 211details. 212 213Miscellaneous Device Configuration 214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 215 216Another task that may be necessary for PCI devices during configuration 217is mapping the video BIOS. On many devices, the VBIOS describes device 218configuration, LCD panel timings (if any), and contains flags indicating 219device state. Mapping the BIOS can be done using the pci_map_rom() 220call, a convenience function that takes care of mapping the actual ROM, 221whether it has been shadowed into memory (typically at address 0xc0000) 222or exists on the PCI device in the ROM BAR. Note that after the ROM has 223been mapped and any necessary information has been extracted, it should 224be unmapped; on many devices, the ROM address decoder is shared with 225other BARs, so leaving it mapped could cause undesired behaviour like 226hangs or memory corruption. 227 228Bus-specific Device Registration and PCI Support 229------------------------------------------------ 230 231A number of functions are provided to help with device registration. The 232functions deal with PCI and platform devices respectively and are only 233provided for historical reasons. These are all deprecated and shouldn't 234be used in new drivers. Besides that there's a few helpers for pci 235drivers. 236 237.. kernel-doc:: drivers/gpu/drm/drm_pci.c 238 :export: 239 240.. kernel-doc:: drivers/gpu/drm/drm_platform.c 241 :export: 242 243Open/Close, File Operations and IOCTLs 244====================================== 245 246Open and Close 247-------------- 248 249Open and close handlers. None of those methods are mandatory:: 250 251 int (*firstopen) (struct drm_device *); 252 void (*lastclose) (struct drm_device *); 253 int (*open) (struct drm_device *, struct drm_file *); 254 void (*preclose) (struct drm_device *, struct drm_file *); 255 void (*postclose) (struct drm_device *, struct drm_file *); 256 257The firstopen method is called by the DRM core for legacy UMS (User Mode 258Setting) drivers only when an application opens a device that has no 259other opened file handle. UMS drivers can implement it to acquire device 260resources. KMS drivers can't use the method and must acquire resources 261in the load method instead. 262 263Similarly the lastclose method is called when the last application 264holding a file handle opened on the device closes it, for both UMS and 265KMS drivers. Additionally, the method is also called at module unload 266time or, for hot-pluggable devices, when the device is unplugged. The 267firstopen and lastclose calls can thus be unbalanced. 268 269The open method is called every time the device is opened by an 270application. Drivers can allocate per-file private data in this method 271and store them in the struct :c:type:`struct drm_file 272<drm_file>` driver_priv field. Note that the open method is 273called before firstopen. 274 275The close operation is split into preclose and postclose methods. 276Drivers must stop and cleanup all per-file operations in the preclose 277method. For instance pending vertical blanking and page flip events must 278be cancelled. No per-file operation is allowed on the file handle after 279returning from the preclose method. 280 281Finally the postclose method is called as the last step of the close 282operation, right before calling the lastclose method if no other open 283file handle exists for the device. Drivers that have allocated per-file 284private data in the open method should free it here. 285 286The lastclose method should restore CRTC and plane properties to default 287value, so that a subsequent open of the device will not inherit state 288from the previous user. It can also be used to execute delayed power 289switching state changes, e.g. in conjunction with the :ref:`vga_switcheroo` 290infrastructure. Beyond that KMS drivers should not do any 291further cleanup. Only legacy UMS drivers might need to clean up device 292state so that the vga console or an independent fbdev driver could take 293over. 294 295File Operations 296--------------- 297 298.. kernel-doc:: drivers/gpu/drm/drm_fops.c 299 :doc: file operations 300 301.. kernel-doc:: drivers/gpu/drm/drm_fops.c 302 :export: 303 304IOCTLs 305------ 306 307struct drm_ioctl_desc \*ioctls; int num_ioctls; 308 Driver-specific ioctls descriptors table. 309 310Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls 311descriptors table is indexed by the ioctl number offset from the base 312value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize 313the table entries. 314 315:: 316 317 DRM_IOCTL_DEF_DRV(ioctl, func, flags) 318 319``ioctl`` is the ioctl name. Drivers must define the DRM_##ioctl and 320DRM_IOCTL_##ioctl macros to the ioctl number offset from 321DRM_COMMAND_BASE and the ioctl number respectively. The first macro is 322private to the device while the second must be exposed to userspace in a 323public header. 324 325``func`` is a pointer to the ioctl handler function compatible with the 326``drm_ioctl_t`` type. 327 328:: 329 330 typedef int drm_ioctl_t(struct drm_device *dev, void *data, 331 struct drm_file *file_priv); 332 333``flags`` is a bitmask combination of the following values. It restricts 334how the ioctl is allowed to be called. 335 336- DRM_AUTH - Only authenticated callers allowed 337 338- DRM_MASTER - The ioctl can only be called on the master file handle 339 340- DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed 341 342- DRM_CONTROL_ALLOW - The ioctl can only be called on a control 343 device 344 345- DRM_UNLOCKED - The ioctl handler will be called without locking the 346 DRM global mutex. This is the enforced default for kms drivers (i.e. 347 using the DRIVER_MODESET flag) and hence shouldn't be used any more 348 for new drivers. 349 350.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c 351 :export: 352 353Legacy Support Code 354=================== 355 356The section very briefly covers some of the old legacy support code 357which is only used by old DRM drivers which have done a so-called 358shadow-attach to the underlying device instead of registering as a real 359driver. This also includes some of the old generic buffer management and 360command submission code. Do not use any of this in new and modern 361drivers. 362 363Legacy Suspend/Resume 364--------------------- 365 366The DRM core provides some suspend/resume code, but drivers wanting full 367suspend/resume support should provide save() and restore() functions. 368These are called at suspend, hibernate, or resume time, and should 369perform any state save or restore required by your device across suspend 370or hibernate states. 371 372int (\*suspend) (struct drm_device \*, pm_message_t state); int 373(\*resume) (struct drm_device \*); 374Those are legacy suspend and resume methods which *only* work with the 375legacy shadow-attach driver registration functions. New driver should 376use the power management interface provided by their bus type (usually 377through the :c:type:`struct device_driver <device_driver>` 378dev_pm_ops) and set these methods to NULL. 379 380Legacy DMA Services 381------------------- 382 383This should cover how DMA mapping etc. is supported by the core. These 384functions are deprecated and should not be used. 385