Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 1 | ============= |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 2 | DRM Internals |
| 3 | ============= |
| 4 | |
| 5 | This chapter documents DRM internals relevant to driver authors and |
| 6 | developers working to add support for the latest features to existing |
| 7 | drivers. |
| 8 | |
| 9 | First, we go over some typical driver initialization requirements, like |
| 10 | setting up command buffers, creating an initial output configuration, |
| 11 | and initializing core services. Subsequent sections cover core internals |
| 12 | in more detail, providing implementation notes and examples. |
| 13 | |
| 14 | The DRM layer provides several services to graphics drivers, many of |
| 15 | them driven by the application interfaces it provides through libdrm, |
| 16 | the library that wraps most of the DRM ioctls. These include vblank |
| 17 | event handling, memory management, output management, framebuffer |
| 18 | management, command submission & fencing, suspend/resume support, and |
| 19 | DMA services. |
| 20 | |
| 21 | Driver Initialization |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 22 | ===================== |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 23 | |
| 24 | At the core of every DRM driver is a :c:type:`struct drm_driver |
| 25 | <drm_driver>` structure. Drivers typically statically initialize |
| 26 | a drm_driver structure, and then pass it to |
Daniel Vetter | 6acc942 | 2019-12-04 11:19:33 +0100 | [diff] [blame] | 27 | drm_dev_alloc() to allocate a device instance. After the |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 28 | device instance is fully initialized it can be registered (which makes |
Daniel Vetter | 6acc942 | 2019-12-04 11:19:33 +0100 | [diff] [blame] | 29 | it accessible from userspace) using drm_dev_register(). |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 30 | |
| 31 | The :c:type:`struct drm_driver <drm_driver>` structure |
| 32 | contains static information that describes the driver and features it |
| 33 | supports, and pointers to methods that the DRM core will call to |
| 34 | implement the DRM API. We will first go through the :c:type:`struct |
| 35 | drm_driver <drm_driver>` static information fields, and will |
| 36 | then describe individual operations in details as they get used in later |
| 37 | sections. |
| 38 | |
| 39 | Driver Information |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 40 | ------------------ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 41 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 42 | Major, Minor and Patchlevel |
Jani Nikula | 2fa91d1 | 2016-06-21 14:49:02 +0300 | [diff] [blame] | 43 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 44 | |
| 45 | int major; int minor; int patchlevel; |
| 46 | The DRM core identifies driver versions by a major, minor and patch |
| 47 | level triplet. The information is printed to the kernel log at |
| 48 | initialization time and passed to userspace through the |
| 49 | DRM_IOCTL_VERSION ioctl. |
| 50 | |
| 51 | The major and minor numbers are also used to verify the requested driver |
| 52 | API version passed to DRM_IOCTL_SET_VERSION. When the driver API |
| 53 | changes between minor versions, applications can call |
| 54 | DRM_IOCTL_SET_VERSION to select a specific version of the API. If the |
| 55 | requested major isn't equal to the driver major, or the requested minor |
| 56 | is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will |
| 57 | return an error. Otherwise the driver's set_version() method will be |
| 58 | called with the requested version. |
| 59 | |
| 60 | Name, Description and Date |
Jani Nikula | 2fa91d1 | 2016-06-21 14:49:02 +0300 | [diff] [blame] | 61 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 62 | |
| 63 | char \*name; char \*desc; char \*date; |
| 64 | The driver name is printed to the kernel log at initialization time, |
| 65 | used for IRQ registration and passed to userspace through |
| 66 | DRM_IOCTL_VERSION. |
| 67 | |
| 68 | The driver description is a purely informative string passed to |
| 69 | userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by |
| 70 | the kernel. |
| 71 | |
| 72 | The driver date, formatted as YYYYMMDD, is meant to identify the date of |
| 73 | the latest modification to the driver. However, as most drivers fail to |
| 74 | update it, its value is mostly useless. The DRM core prints it to the |
| 75 | kernel log at initialization time and passes it to userspace through the |
| 76 | DRM_IOCTL_VERSION ioctl. |
| 77 | |
Thomas Zimmermann | 52506b0 | 2021-12-22 09:28:22 +0100 | [diff] [blame] | 78 | Module Initialization |
| 79 | --------------------- |
| 80 | |
| 81 | .. kernel-doc:: include/drm/drm_module.h |
| 82 | :doc: overview |
| 83 | |
Thomas Zimmermann | 2916059 | 2021-04-12 15:10:41 +0200 | [diff] [blame] | 84 | Managing Ownership of the Framebuffer Aperture |
| 85 | ---------------------------------------------- |
| 86 | |
| 87 | .. kernel-doc:: drivers/gpu/drm/drm_aperture.c |
| 88 | :doc: overview |
| 89 | |
| 90 | .. kernel-doc:: include/drm/drm_aperture.h |
| 91 | :internal: |
| 92 | |
| 93 | .. kernel-doc:: drivers/gpu/drm/drm_aperture.c |
| 94 | :export: |
| 95 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 96 | Device Instance and Driver Handling |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 97 | ----------------------------------- |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 98 | |
| 99 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c |
| 100 | :doc: driver instance overview |
| 101 | |
Daniel Vetter | 3214a16 | 2019-01-11 17:40:48 +0100 | [diff] [blame] | 102 | .. kernel-doc:: include/drm/drm_device.h |
| 103 | :internal: |
| 104 | |
Daniel Vetter | 6c4789e | 2016-11-14 12:58:20 +0100 | [diff] [blame] | 105 | .. kernel-doc:: include/drm/drm_drv.h |
| 106 | :internal: |
| 107 | |
Daniel Vetter | 1ea3576 | 2017-03-02 16:16:36 +0100 | [diff] [blame] | 108 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c |
| 109 | :export: |
| 110 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 111 | Driver Load |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 112 | ----------- |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 113 | |
Daniel Vetter | 86ab67d | 2019-02-12 17:46:15 +0100 | [diff] [blame] | 114 | Component Helper Usage |
| 115 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 116 | |
| 117 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c |
| 118 | :doc: component helper usage recommendations |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 119 | |
| 120 | Memory Manager Initialization |
Jani Nikula | 2fa91d1 | 2016-06-21 14:49:02 +0300 | [diff] [blame] | 121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 122 | |
| 123 | Every DRM driver requires a memory manager which must be initialized at |
| 124 | load time. DRM currently contains two memory managers, the Translation |
| 125 | Table Manager (TTM) and the Graphics Execution Manager (GEM). This |
| 126 | document describes the use of the GEM memory manager only. See ? for |
| 127 | details. |
| 128 | |
| 129 | Miscellaneous Device Configuration |
Jani Nikula | 2fa91d1 | 2016-06-21 14:49:02 +0300 | [diff] [blame] | 130 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 131 | |
| 132 | Another task that may be necessary for PCI devices during configuration |
| 133 | is mapping the video BIOS. On many devices, the VBIOS describes device |
| 134 | configuration, LCD panel timings (if any), and contains flags indicating |
| 135 | device state. Mapping the BIOS can be done using the pci_map_rom() |
| 136 | call, a convenience function that takes care of mapping the actual ROM, |
| 137 | whether it has been shadowed into memory (typically at address 0xc0000) |
| 138 | or exists on the PCI device in the ROM BAR. Note that after the ROM has |
| 139 | been mapped and any necessary information has been extracted, it should |
| 140 | be unmapped; on many devices, the ROM address decoder is shared with |
| 141 | other BARs, so leaving it mapped could cause undesired behaviour like |
| 142 | hangs or memory corruption. |
| 143 | |
Daniel Vetter | c6603c7 | 2020-03-24 13:45:40 +0100 | [diff] [blame] | 144 | Managed Resources |
| 145 | ----------------- |
| 146 | |
| 147 | .. kernel-doc:: drivers/gpu/drm/drm_managed.c |
| 148 | :doc: managed resources |
| 149 | |
Daniel Vetter | 9e1ed9f | 2020-03-23 15:49:50 +0100 | [diff] [blame] | 150 | .. kernel-doc:: drivers/gpu/drm/drm_managed.c |
| 151 | :export: |
| 152 | |
| 153 | .. kernel-doc:: include/drm/drm_managed.h |
| 154 | :internal: |
| 155 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 156 | Bus-specific Device Registration and PCI Support |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 157 | ------------------------------------------------ |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 158 | |
| 159 | A number of functions are provided to help with device registration. The |
| 160 | functions deal with PCI and platform devices respectively and are only |
| 161 | provided for historical reasons. These are all deprecated and shouldn't |
| 162 | be used in new drivers. Besides that there's a few helpers for pci |
| 163 | drivers. |
| 164 | |
| 165 | .. kernel-doc:: drivers/gpu/drm/drm_pci.c |
| 166 | :export: |
| 167 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 168 | Open/Close, File Operations and IOCTLs |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 169 | ====================================== |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 170 | |
Daniel Vetter | bb2eaba | 2017-05-31 11:20:45 +0200 | [diff] [blame] | 171 | .. _drm_driver_fops: |
| 172 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 173 | File Operations |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 174 | --------------- |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 175 | |
Daniel Vetter | 9acdac6 | 2017-03-08 15:12:40 +0100 | [diff] [blame] | 176 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 177 | :doc: file operations |
| 178 | |
Daniel Vetter | b93658f | 2017-03-08 15:12:44 +0100 | [diff] [blame] | 179 | .. kernel-doc:: include/drm/drm_file.h |
| 180 | :internal: |
| 181 | |
Daniel Vetter | 9acdac6 | 2017-03-08 15:12:40 +0100 | [diff] [blame] | 182 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 183 | :export: |
| 184 | |
Rob Clark | d8187177 | 2016-11-05 11:08:07 -0400 | [diff] [blame] | 185 | Misc Utilities |
| 186 | ============== |
| 187 | |
| 188 | Printer |
| 189 | ------- |
| 190 | |
| 191 | .. kernel-doc:: include/drm/drm_print.h |
| 192 | :doc: print |
| 193 | |
| 194 | .. kernel-doc:: include/drm/drm_print.h |
| 195 | :internal: |
| 196 | |
Daniel Vetter | 2d5e836d | 2016-11-14 12:58:22 +0100 | [diff] [blame] | 197 | .. kernel-doc:: drivers/gpu/drm/drm_print.c |
Rob Clark | d8187177 | 2016-11-05 11:08:07 -0400 | [diff] [blame] | 198 | :export: |
| 199 | |
Sam Ravnborg | e9eafcb | 2019-01-12 20:32:44 +0100 | [diff] [blame] | 200 | Utilities |
| 201 | --------- |
| 202 | |
| 203 | .. kernel-doc:: include/drm/drm_util.h |
| 204 | :doc: drm utils |
| 205 | |
| 206 | .. kernel-doc:: include/drm/drm_util.h |
| 207 | :internal: |
| 208 | |
Rob Clark | d8187177 | 2016-11-05 11:08:07 -0400 | [diff] [blame] | 209 | |
José Expósito | 6fde8ee | 2022-06-20 18:06:40 +0200 | [diff] [blame] | 210 | Unit testing |
| 211 | ============ |
| 212 | |
| 213 | KUnit |
| 214 | ----- |
| 215 | |
| 216 | KUnit (Kernel unit testing framework) provides a common framework for unit tests |
| 217 | within the Linux kernel. |
| 218 | |
| 219 | This section covers the specifics for the DRM subsystem. For general information |
| 220 | about KUnit, please refer to Documentation/dev-tools/kunit/start.rst. |
| 221 | |
| 222 | How to run the tests? |
| 223 | ~~~~~~~~~~~~~~~~~~~~~ |
| 224 | |
| 225 | In order to facilitate running the test suite, a configuration file is present |
| 226 | in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as |
| 227 | follows: |
| 228 | |
| 229 | .. code-block:: bash |
| 230 | |
| 231 | $ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \ |
| 232 | --kconfig_add CONFIG_VIRTIO_UML=y \ |
| 233 | --kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y |
| 234 | |
| 235 | .. note:: |
| 236 | The configuration included in ``.kunitconfig`` should be as generic as |
| 237 | possible. |
| 238 | ``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not |
| 239 | included in it because they are only required for User Mode Linux. |
| 240 | |
| 241 | |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 242 | Legacy Support Code |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 243 | =================== |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 244 | |
| 245 | The section very briefly covers some of the old legacy support code |
| 246 | which is only used by old DRM drivers which have done a so-called |
| 247 | shadow-attach to the underlying device instead of registering as a real |
| 248 | driver. This also includes some of the old generic buffer management and |
| 249 | command submission code. Do not use any of this in new and modern |
| 250 | drivers. |
| 251 | |
| 252 | Legacy Suspend/Resume |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 253 | --------------------- |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 254 | |
| 255 | The DRM core provides some suspend/resume code, but drivers wanting full |
| 256 | suspend/resume support should provide save() and restore() functions. |
| 257 | These are called at suspend, hibernate, or resume time, and should |
| 258 | perform any state save or restore required by your device across suspend |
| 259 | or hibernate states. |
| 260 | |
| 261 | int (\*suspend) (struct drm_device \*, pm_message_t state); int |
| 262 | (\*resume) (struct drm_device \*); |
| 263 | Those are legacy suspend and resume methods which *only* work with the |
| 264 | legacy shadow-attach driver registration functions. New driver should |
| 265 | use the power management interface provided by their bus type (usually |
| 266 | through the :c:type:`struct device_driver <device_driver>` |
| 267 | dev_pm_ops) and set these methods to NULL. |
| 268 | |
| 269 | Legacy DMA Services |
Jani Nikula | 2255402 | 2016-06-21 14:49:00 +0300 | [diff] [blame] | 270 | ------------------- |
Jani Nikula | ca00c2b | 2016-06-21 14:48:58 +0300 | [diff] [blame] | 271 | |
| 272 | This should cover how DMA mapping etc. is supported by the core. These |
| 273 | functions are deprecated and should not be used. |