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 21.. contents:: 22 23Driver Initialization 24===================== 25 26At the core of every DRM driver is a :c:type:`struct drm_driver 27<drm_driver>` structure. Drivers typically statically initialize 28a drm_driver structure, and then pass it to 29drm_dev_alloc() to allocate a device instance. After the 30device instance is fully initialized it can be registered (which makes 31it accessible from userspace) using drm_dev_register(). 32 33The :c:type:`struct drm_driver <drm_driver>` structure 34contains static information that describes the driver and features it 35supports, and pointers to methods that the DRM core will call to 36implement the DRM API. We will first go through the :c:type:`struct 37drm_driver <drm_driver>` static information fields, and will 38then describe individual operations in details as they get used in later 39sections. 40 41Driver Information 42------------------ 43 44Major, Minor and Patchlevel 45~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47int major; int minor; int patchlevel; 48The DRM core identifies driver versions by a major, minor and patch 49level triplet. The information is printed to the kernel log at 50initialization time and passed to userspace through the 51DRM_IOCTL_VERSION ioctl. 52 53The major and minor numbers are also used to verify the requested driver 54API version passed to DRM_IOCTL_SET_VERSION. When the driver API 55changes between minor versions, applications can call 56DRM_IOCTL_SET_VERSION to select a specific version of the API. If the 57requested major isn't equal to the driver major, or the requested minor 58is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will 59return an error. Otherwise the driver's set_version() method will be 60called with the requested version. 61 62Name and Description 63~~~~~~~~~~~~~~~~~~~~ 64 65char \*name; char \*desc; char \*date; 66The driver name is printed to the kernel log at initialization time, 67used for IRQ registration and passed to userspace through 68DRM_IOCTL_VERSION. 69 70The driver description is a purely informative string passed to 71userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by 72the kernel. 73 74Module Initialization 75--------------------- 76 77.. kernel-doc:: include/drm/drm_module.h 78 :doc: overview 79 80Device Instance and Driver Handling 81----------------------------------- 82 83.. kernel-doc:: drivers/gpu/drm/drm_drv.c 84 :doc: driver instance overview 85 86.. kernel-doc:: include/drm/drm_device.h 87 :internal: 88 89.. kernel-doc:: include/drm/drm_drv.h 90 :internal: 91 92.. kernel-doc:: drivers/gpu/drm/drm_drv.c 93 :export: 94 95Driver Load 96----------- 97 98Component Helper Usage 99~~~~~~~~~~~~~~~~~~~~~~ 100 101.. kernel-doc:: drivers/gpu/drm/drm_drv.c 102 :doc: component helper usage recommendations 103 104Memory Manager Initialization 105~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 106 107Every DRM driver requires a memory manager which must be initialized at 108load time. DRM currently contains two memory managers, the Translation 109Table Manager (TTM) and the Graphics Execution Manager (GEM). This 110document describes the use of the GEM memory manager only. See ? for 111details. 112 113Miscellaneous Device Configuration 114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 115 116Another task that may be necessary for PCI devices during configuration 117is mapping the video BIOS. On many devices, the VBIOS describes device 118configuration, LCD panel timings (if any), and contains flags indicating 119device state. Mapping the BIOS can be done using the pci_map_rom() 120call, a convenience function that takes care of mapping the actual ROM, 121whether it has been shadowed into memory (typically at address 0xc0000) 122or exists on the PCI device in the ROM BAR. Note that after the ROM has 123been mapped and any necessary information has been extracted, it should 124be unmapped; on many devices, the ROM address decoder is shared with 125other BARs, so leaving it mapped could cause undesired behaviour like 126hangs or memory corruption. 127 128Managed Resources 129----------------- 130 131.. kernel-doc:: drivers/gpu/drm/drm_managed.c 132 :doc: managed resources 133 134.. kernel-doc:: drivers/gpu/drm/drm_managed.c 135 :export: 136 137.. kernel-doc:: include/drm/drm_managed.h 138 :internal: 139 140Open/Close, File Operations and IOCTLs 141====================================== 142 143.. _drm_driver_fops: 144 145File Operations 146--------------- 147 148.. kernel-doc:: drivers/gpu/drm/drm_file.c 149 :doc: file operations 150 151.. kernel-doc:: include/drm/drm_file.h 152 :internal: 153 154.. kernel-doc:: drivers/gpu/drm/drm_file.c 155 :export: 156 157Misc Utilities 158============== 159 160Printer 161------- 162 163.. kernel-doc:: include/drm/drm_print.h 164 :doc: print 165 166.. kernel-doc:: include/drm/drm_print.h 167 :internal: 168 169.. kernel-doc:: drivers/gpu/drm/drm_print.c 170 :export: 171 172Utilities 173--------- 174 175.. kernel-doc:: include/drm/drm_util.h 176 :doc: drm utils 177 178.. kernel-doc:: include/drm/drm_util.h 179 :internal: 180 181 182Unit testing 183============ 184 185KUnit 186----- 187 188KUnit (Kernel unit testing framework) provides a common framework for unit tests 189within the Linux kernel. 190 191This section covers the specifics for the DRM subsystem. For general information 192about KUnit, please refer to Documentation/dev-tools/kunit/start.rst. 193 194How to run the tests? 195~~~~~~~~~~~~~~~~~~~~~ 196 197In order to facilitate running the test suite, a configuration file is present 198in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as 199follows: 200 201.. code-block:: bash 202 203 $ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \ 204 --kconfig_add CONFIG_VIRTIO_UML=y \ 205 --kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y 206 207.. note:: 208 The configuration included in ``.kunitconfig`` should be as generic as 209 possible. 210 ``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not 211 included in it because they are only required for User Mode Linux. 212 213KUnit Coverage Rules 214~~~~~~~~~~~~~~~~~~~~ 215 216KUnit support is gradually added to the DRM framework and helpers. There's no 217general requirement for the framework and helpers to have KUnit tests at the 218moment. However, patches that are affecting a function or helper already 219covered by KUnit tests must provide tests if the change calls for one. 220 221Legacy Support Code 222=================== 223 224The section very briefly covers some of the old legacy support code 225which is only used by old DRM drivers which have done a so-called 226shadow-attach to the underlying device instead of registering as a real 227driver. This also includes some of the old generic buffer management and 228command submission code. Do not use any of this in new and modern 229drivers. 230 231Legacy Suspend/Resume 232--------------------- 233 234The DRM core provides some suspend/resume code, but drivers wanting full 235suspend/resume support should provide save() and restore() functions. 236These are called at suspend, hibernate, or resume time, and should 237perform any state save or restore required by your device across suspend 238or hibernate states. 239 240int (\*suspend) (struct drm_device \*, pm_message_t state); int 241(\*resume) (struct drm_device \*); 242Those are legacy suspend and resume methods which *only* work with the 243legacy shadow-attach driver registration functions. New driver should 244use the power management interface provided by their bus type (usually 245through the :c:type:`struct device_driver <device_driver>` 246dev_pm_ops) and set these methods to NULL. 247 248Legacy DMA Services 249------------------- 250 251This should cover how DMA mapping etc. is supported by the core. These 252functions are deprecated and should not be used. 253