0001 =============
0002 DRM Internals
0003 =============
0004
0005 This chapter documents DRM internals relevant to driver authors and
0006 developers working to add support for the latest features to existing
0007 drivers.
0008
0009 First, we go over some typical driver initialization requirements, like
0010 setting up command buffers, creating an initial output configuration,
0011 and initializing core services. Subsequent sections cover core internals
0012 in more detail, providing implementation notes and examples.
0013
0014 The DRM layer provides several services to graphics drivers, many of
0015 them driven by the application interfaces it provides through libdrm,
0016 the library that wraps most of the DRM ioctls. These include vblank
0017 event handling, memory management, output management, framebuffer
0018 management, command submission & fencing, suspend/resume support, and
0019 DMA services.
0020
0021 Driver Initialization
0022 =====================
0023
0024 At the core of every DRM driver is a :c:type:`struct drm_driver
0025 <drm_driver>` structure. Drivers typically statically initialize
0026 a drm_driver structure, and then pass it to
0027 drm_dev_alloc() to allocate a device instance. After the
0028 device instance is fully initialized it can be registered (which makes
0029 it accessible from userspace) using drm_dev_register().
0030
0031 The :c:type:`struct drm_driver <drm_driver>` structure
0032 contains static information that describes the driver and features it
0033 supports, and pointers to methods that the DRM core will call to
0034 implement the DRM API. We will first go through the :c:type:`struct
0035 drm_driver <drm_driver>` static information fields, and will
0036 then describe individual operations in details as they get used in later
0037 sections.
0038
0039 Driver Information
0040 ------------------
0041
0042 Major, Minor and Patchlevel
0043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0044
0045 int major; int minor; int patchlevel;
0046 The DRM core identifies driver versions by a major, minor and patch
0047 level triplet. The information is printed to the kernel log at
0048 initialization time and passed to userspace through the
0049 DRM_IOCTL_VERSION ioctl.
0050
0051 The major and minor numbers are also used to verify the requested driver
0052 API version passed to DRM_IOCTL_SET_VERSION. When the driver API
0053 changes between minor versions, applications can call
0054 DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
0055 requested major isn't equal to the driver major, or the requested minor
0056 is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
0057 return an error. Otherwise the driver's set_version() method will be
0058 called with the requested version.
0059
0060 Name, Description and Date
0061 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0062
0063 char \*name; char \*desc; char \*date;
0064 The driver name is printed to the kernel log at initialization time,
0065 used for IRQ registration and passed to userspace through
0066 DRM_IOCTL_VERSION.
0067
0068 The driver description is a purely informative string passed to
0069 userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
0070 the kernel.
0071
0072 The driver date, formatted as YYYYMMDD, is meant to identify the date of
0073 the latest modification to the driver. However, as most drivers fail to
0074 update it, its value is mostly useless. The DRM core prints it to the
0075 kernel log at initialization time and passes it to userspace through the
0076 DRM_IOCTL_VERSION ioctl.
0077
0078 Module Initialization
0079 ---------------------
0080
0081 .. kernel-doc:: include/drm/drm_module.h
0082 :doc: overview
0083
0084 Managing Ownership of the Framebuffer Aperture
0085 ----------------------------------------------
0086
0087 .. kernel-doc:: drivers/gpu/drm/drm_aperture.c
0088 :doc: overview
0089
0090 .. kernel-doc:: include/drm/drm_aperture.h
0091 :internal:
0092
0093 .. kernel-doc:: drivers/gpu/drm/drm_aperture.c
0094 :export:
0095
0096 Device Instance and Driver Handling
0097 -----------------------------------
0098
0099 .. kernel-doc:: drivers/gpu/drm/drm_drv.c
0100 :doc: driver instance overview
0101
0102 .. kernel-doc:: include/drm/drm_device.h
0103 :internal:
0104
0105 .. kernel-doc:: include/drm/drm_drv.h
0106 :internal:
0107
0108 .. kernel-doc:: drivers/gpu/drm/drm_drv.c
0109 :export:
0110
0111 Driver Load
0112 -----------
0113
0114 Component Helper Usage
0115 ~~~~~~~~~~~~~~~~~~~~~~
0116
0117 .. kernel-doc:: drivers/gpu/drm/drm_drv.c
0118 :doc: component helper usage recommendations
0119
0120 Memory Manager Initialization
0121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0122
0123 Every DRM driver requires a memory manager which must be initialized at
0124 load time. DRM currently contains two memory managers, the Translation
0125 Table Manager (TTM) and the Graphics Execution Manager (GEM). This
0126 document describes the use of the GEM memory manager only. See ? for
0127 details.
0128
0129 Miscellaneous Device Configuration
0130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0131
0132 Another task that may be necessary for PCI devices during configuration
0133 is mapping the video BIOS. On many devices, the VBIOS describes device
0134 configuration, LCD panel timings (if any), and contains flags indicating
0135 device state. Mapping the BIOS can be done using the pci_map_rom()
0136 call, a convenience function that takes care of mapping the actual ROM,
0137 whether it has been shadowed into memory (typically at address 0xc0000)
0138 or exists on the PCI device in the ROM BAR. Note that after the ROM has
0139 been mapped and any necessary information has been extracted, it should
0140 be unmapped; on many devices, the ROM address decoder is shared with
0141 other BARs, so leaving it mapped could cause undesired behaviour like
0142 hangs or memory corruption.
0143
0144 Managed Resources
0145 -----------------
0146
0147 .. kernel-doc:: drivers/gpu/drm/drm_managed.c
0148 :doc: managed resources
0149
0150 .. kernel-doc:: drivers/gpu/drm/drm_managed.c
0151 :export:
0152
0153 .. kernel-doc:: include/drm/drm_managed.h
0154 :internal:
0155
0156 Bus-specific Device Registration and PCI Support
0157 ------------------------------------------------
0158
0159 A number of functions are provided to help with device registration. The
0160 functions deal with PCI and platform devices respectively and are only
0161 provided for historical reasons. These are all deprecated and shouldn't
0162 be used in new drivers. Besides that there's a few helpers for pci
0163 drivers.
0164
0165 .. kernel-doc:: drivers/gpu/drm/drm_pci.c
0166 :export:
0167
0168 Open/Close, File Operations and IOCTLs
0169 ======================================
0170
0171 .. _drm_driver_fops:
0172
0173 File Operations
0174 ---------------
0175
0176 .. kernel-doc:: drivers/gpu/drm/drm_file.c
0177 :doc: file operations
0178
0179 .. kernel-doc:: include/drm/drm_file.h
0180 :internal:
0181
0182 .. kernel-doc:: drivers/gpu/drm/drm_file.c
0183 :export:
0184
0185 Misc Utilities
0186 ==============
0187
0188 Printer
0189 -------
0190
0191 .. kernel-doc:: include/drm/drm_print.h
0192 :doc: print
0193
0194 .. kernel-doc:: include/drm/drm_print.h
0195 :internal:
0196
0197 .. kernel-doc:: drivers/gpu/drm/drm_print.c
0198 :export:
0199
0200 Utilities
0201 ---------
0202
0203 .. kernel-doc:: include/drm/drm_util.h
0204 :doc: drm utils
0205
0206 .. kernel-doc:: include/drm/drm_util.h
0207 :internal:
0208
0209
0210 Unit testing
0211 ============
0212
0213 KUnit
0214 -----
0215
0216 KUnit (Kernel unit testing framework) provides a common framework for unit tests
0217 within the Linux kernel.
0218
0219 This section covers the specifics for the DRM subsystem. For general information
0220 about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.
0221
0222 How to run the tests?
0223 ~~~~~~~~~~~~~~~~~~~~~
0224
0225 In order to facilitate running the test suite, a configuration file is present
0226 in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as
0227 follows:
0228
0229 .. code-block:: bash
0230
0231 $ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \
0232 --kconfig_add CONFIG_VIRTIO_UML=y \
0233 --kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y
0234
0235 .. note::
0236 The configuration included in ``.kunitconfig`` should be as generic as
0237 possible.
0238 ``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not
0239 included in it because they are only required for User Mode Linux.
0240
0241
0242 Legacy Support Code
0243 ===================
0244
0245 The section very briefly covers some of the old legacy support code
0246 which is only used by old DRM drivers which have done a so-called
0247 shadow-attach to the underlying device instead of registering as a real
0248 driver. This also includes some of the old generic buffer management and
0249 command submission code. Do not use any of this in new and modern
0250 drivers.
0251
0252 Legacy Suspend/Resume
0253 ---------------------
0254
0255 The DRM core provides some suspend/resume code, but drivers wanting full
0256 suspend/resume support should provide save() and restore() functions.
0257 These are called at suspend, hibernate, or resume time, and should
0258 perform any state save or restore required by your device across suspend
0259 or hibernate states.
0260
0261 int (\*suspend) (struct drm_device \*, pm_message_t state); int
0262 (\*resume) (struct drm_device \*);
0263 Those are legacy suspend and resume methods which *only* work with the
0264 legacy shadow-attach driver registration functions. New driver should
0265 use the power management interface provided by their bus type (usually
0266 through the :c:type:`struct device_driver <device_driver>`
0267 dev_pm_ops) and set these methods to NULL.
0268
0269 Legacy DMA Services
0270 -------------------
0271
0272 This should cover how DMA mapping etc. is supported by the core. These
0273 functions are deprecated and should not be used.
