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 101DRIVER_SYNCOBJ 102 Driver support drm sync objects. 103 104Major, Minor and Patchlevel 105~~~~~~~~~~~~~~~~~~~~~~~~~~~ 106 107int major; int minor; int patchlevel; 108The DRM core identifies driver versions by a major, minor and patch 109level triplet. The information is printed to the kernel log at 110initialization time and passed to userspace through the 111DRM_IOCTL_VERSION ioctl. 112 113The major and minor numbers are also used to verify the requested driver 114API version passed to DRM_IOCTL_SET_VERSION. When the driver API 115changes between minor versions, applications can call 116DRM_IOCTL_SET_VERSION to select a specific version of the API. If the 117requested major isn't equal to the driver major, or the requested minor 118is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will 119return an error. Otherwise the driver's set_version() method will be 120called with the requested version. 121 122Name, Description and Date 123~~~~~~~~~~~~~~~~~~~~~~~~~~ 124 125char \*name; char \*desc; char \*date; 126The driver name is printed to the kernel log at initialization time, 127used for IRQ registration and passed to userspace through 128DRM_IOCTL_VERSION. 129 130The driver description is a purely informative string passed to 131userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by 132the kernel. 133 134The driver date, formatted as YYYYMMDD, is meant to identify the date of 135the latest modification to the driver. However, as most drivers fail to 136update it, its value is mostly useless. The DRM core prints it to the 137kernel log at initialization time and passes it to userspace through the 138DRM_IOCTL_VERSION ioctl. 139 140Device Instance and Driver Handling 141----------------------------------- 142 143.. kernel-doc:: drivers/gpu/drm/drm_drv.c 144 :doc: driver instance overview 145 146.. kernel-doc:: include/drm/drm_drv.h 147 :internal: 148 149.. kernel-doc:: drivers/gpu/drm/drm_drv.c 150 :export: 151 152Driver Load 153----------- 154 155 156IRQ Helper Library 157~~~~~~~~~~~~~~~~~~ 158 159.. kernel-doc:: drivers/gpu/drm/drm_irq.c 160 :doc: irq helpers 161 162.. kernel-doc:: drivers/gpu/drm/drm_irq.c 163 :export: 164 165Memory Manager Initialization 166~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 167 168Every DRM driver requires a memory manager which must be initialized at 169load time. DRM currently contains two memory managers, the Translation 170Table Manager (TTM) and the Graphics Execution Manager (GEM). This 171document describes the use of the GEM memory manager only. See ? for 172details. 173 174Miscellaneous Device Configuration 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177Another task that may be necessary for PCI devices during configuration 178is mapping the video BIOS. On many devices, the VBIOS describes device 179configuration, LCD panel timings (if any), and contains flags indicating 180device state. Mapping the BIOS can be done using the pci_map_rom() 181call, a convenience function that takes care of mapping the actual ROM, 182whether it has been shadowed into memory (typically at address 0xc0000) 183or exists on the PCI device in the ROM BAR. Note that after the ROM has 184been mapped and any necessary information has been extracted, it should 185be unmapped; on many devices, the ROM address decoder is shared with 186other BARs, so leaving it mapped could cause undesired behaviour like 187hangs or memory corruption. 188 189Bus-specific Device Registration and PCI Support 190------------------------------------------------ 191 192A number of functions are provided to help with device registration. The 193functions deal with PCI and platform devices respectively and are only 194provided for historical reasons. These are all deprecated and shouldn't 195be used in new drivers. Besides that there's a few helpers for pci 196drivers. 197 198.. kernel-doc:: drivers/gpu/drm/drm_pci.c 199 :export: 200 201Open/Close, File Operations and IOCTLs 202====================================== 203 204File Operations 205--------------- 206 207.. kernel-doc:: drivers/gpu/drm/drm_file.c 208 :doc: file operations 209 210.. kernel-doc:: include/drm/drm_file.h 211 :internal: 212 213.. kernel-doc:: drivers/gpu/drm/drm_file.c 214 :export: 215 216Misc Utilities 217============== 218 219Printer 220------- 221 222.. kernel-doc:: include/drm/drm_print.h 223 :doc: print 224 225.. kernel-doc:: include/drm/drm_print.h 226 :internal: 227 228.. kernel-doc:: drivers/gpu/drm/drm_print.c 229 :export: 230 231 232Legacy Support Code 233=================== 234 235The section very briefly covers some of the old legacy support code 236which is only used by old DRM drivers which have done a so-called 237shadow-attach to the underlying device instead of registering as a real 238driver. This also includes some of the old generic buffer management and 239command submission code. Do not use any of this in new and modern 240drivers. 241 242Legacy Suspend/Resume 243--------------------- 244 245The DRM core provides some suspend/resume code, but drivers wanting full 246suspend/resume support should provide save() and restore() functions. 247These are called at suspend, hibernate, or resume time, and should 248perform any state save or restore required by your device across suspend 249or hibernate states. 250 251int (\*suspend) (struct drm_device \*, pm_message_t state); int 252(\*resume) (struct drm_device \*); 253Those are legacy suspend and resume methods which *only* work with the 254legacy shadow-attach driver registration functions. New driver should 255use the power management interface provided by their bus type (usually 256through the :c:type:`struct device_driver <device_driver>` 257dev_pm_ops) and set these methods to NULL. 258 259Legacy DMA Services 260------------------- 261 262This should cover how DMA mapping etc. is supported by the core. These 263functions are deprecated and should not be used. 264