256 lines · plain
1=============2DRM Internals3=============4 5This chapter documents DRM internals relevant to driver authors and6developers working to add support for the latest features to existing7drivers.8 9First, we go over some typical driver initialization requirements, like10setting up command buffers, creating an initial output configuration,11and initializing core services. Subsequent sections cover core internals12in more detail, providing implementation notes and examples.13 14The DRM layer provides several services to graphics drivers, many of15them driven by the application interfaces it provides through libdrm,16the library that wraps most of the DRM ioctls. These include vblank17event handling, memory management, output management, framebuffer18management, command submission & fencing, suspend/resume support, and19DMA services.20 21Driver Initialization22=====================23 24At the core of every DRM driver is a :c:type:`struct drm_driver25<drm_driver>` structure. Drivers typically statically initialize26a drm_driver structure, and then pass it to27drm_dev_alloc() to allocate a device instance. After the28device instance is fully initialized it can be registered (which makes29it accessible from userspace) using drm_dev_register().30 31The :c:type:`struct drm_driver <drm_driver>` structure32contains static information that describes the driver and features it33supports, and pointers to methods that the DRM core will call to34implement the DRM API. We will first go through the :c:type:`struct35drm_driver <drm_driver>` static information fields, and will36then describe individual operations in details as they get used in later37sections.38 39Driver Information40------------------41 42Major, Minor and Patchlevel43~~~~~~~~~~~~~~~~~~~~~~~~~~~44 45int major; int minor; int patchlevel;46The DRM core identifies driver versions by a major, minor and patch47level triplet. The information is printed to the kernel log at48initialization time and passed to userspace through the49DRM_IOCTL_VERSION ioctl.50 51The major and minor numbers are also used to verify the requested driver52API version passed to DRM_IOCTL_SET_VERSION. When the driver API53changes between minor versions, applications can call54DRM_IOCTL_SET_VERSION to select a specific version of the API. If the55requested major isn't equal to the driver major, or the requested minor56is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will57return an error. Otherwise the driver's set_version() method will be58called with the requested version.59 60Name and Description61~~~~~~~~~~~~~~~~~~~~62 63char \*name; char \*desc; char \*date;64The driver name is printed to the kernel log at initialization time,65used for IRQ registration and passed to userspace through66DRM_IOCTL_VERSION.67 68The driver description is a purely informative string passed to69userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by70the kernel.71 72Module Initialization73---------------------74 75.. kernel-doc:: include/drm/drm_module.h76 :doc: overview77 78Managing Ownership of the Framebuffer Aperture79----------------------------------------------80 81.. kernel-doc:: drivers/gpu/drm/drm_aperture.c82 :doc: overview83 84.. kernel-doc:: include/drm/drm_aperture.h85 :internal:86 87.. kernel-doc:: drivers/gpu/drm/drm_aperture.c88 :export:89 90Device Instance and Driver Handling91-----------------------------------92 93.. kernel-doc:: drivers/gpu/drm/drm_drv.c94 :doc: driver instance overview95 96.. kernel-doc:: include/drm/drm_device.h97 :internal:98 99.. kernel-doc:: include/drm/drm_drv.h100 :internal:101 102.. kernel-doc:: drivers/gpu/drm/drm_drv.c103 :export:104 105Driver Load106-----------107 108Component Helper Usage109~~~~~~~~~~~~~~~~~~~~~~110 111.. kernel-doc:: drivers/gpu/drm/drm_drv.c112 :doc: component helper usage recommendations113 114Memory Manager Initialization115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~116 117Every DRM driver requires a memory manager which must be initialized at118load time. DRM currently contains two memory managers, the Translation119Table Manager (TTM) and the Graphics Execution Manager (GEM). This120document describes the use of the GEM memory manager only. See ? for121details.122 123Miscellaneous Device Configuration124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~125 126Another task that may be necessary for PCI devices during configuration127is mapping the video BIOS. On many devices, the VBIOS describes device128configuration, LCD panel timings (if any), and contains flags indicating129device state. Mapping the BIOS can be done using the pci_map_rom()130call, a convenience function that takes care of mapping the actual ROM,131whether it has been shadowed into memory (typically at address 0xc0000)132or exists on the PCI device in the ROM BAR. Note that after the ROM has133been mapped and any necessary information has been extracted, it should134be unmapped; on many devices, the ROM address decoder is shared with135other BARs, so leaving it mapped could cause undesired behaviour like136hangs or memory corruption.137 138Managed Resources139-----------------140 141.. kernel-doc:: drivers/gpu/drm/drm_managed.c142 :doc: managed resources143 144.. kernel-doc:: drivers/gpu/drm/drm_managed.c145 :export:146 147.. kernel-doc:: include/drm/drm_managed.h148 :internal:149 150Open/Close, File Operations and IOCTLs151======================================152 153.. _drm_driver_fops:154 155File Operations156---------------157 158.. kernel-doc:: drivers/gpu/drm/drm_file.c159 :doc: file operations160 161.. kernel-doc:: include/drm/drm_file.h162 :internal:163 164.. kernel-doc:: drivers/gpu/drm/drm_file.c165 :export:166 167Misc Utilities168==============169 170Printer171-------172 173.. kernel-doc:: include/drm/drm_print.h174 :doc: print175 176.. kernel-doc:: include/drm/drm_print.h177 :internal:178 179.. kernel-doc:: drivers/gpu/drm/drm_print.c180 :export:181 182Utilities183---------184 185.. kernel-doc:: include/drm/drm_util.h186 :doc: drm utils187 188.. kernel-doc:: include/drm/drm_util.h189 :internal:190 191 192Unit testing193============194 195KUnit196-----197 198KUnit (Kernel unit testing framework) provides a common framework for unit tests199within the Linux kernel.200 201This section covers the specifics for the DRM subsystem. For general information202about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.203 204How to run the tests?205~~~~~~~~~~~~~~~~~~~~~206 207In order to facilitate running the test suite, a configuration file is present208in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as209follows:210 211.. code-block:: bash212 213 $ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \214 --kconfig_add CONFIG_VIRTIO_UML=y \215 --kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y216 217.. note::218 The configuration included in ``.kunitconfig`` should be as generic as219 possible.220 ``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not221 included in it because they are only required for User Mode Linux.222 223 224Legacy Support Code225===================226 227The section very briefly covers some of the old legacy support code228which is only used by old DRM drivers which have done a so-called229shadow-attach to the underlying device instead of registering as a real230driver. This also includes some of the old generic buffer management and231command submission code. Do not use any of this in new and modern232drivers.233 234Legacy Suspend/Resume235---------------------236 237The DRM core provides some suspend/resume code, but drivers wanting full238suspend/resume support should provide save() and restore() functions.239These are called at suspend, hibernate, or resume time, and should240perform any state save or restore required by your device across suspend241or hibernate states.242 243int (\*suspend) (struct drm_device \*, pm_message_t state); int244(\*resume) (struct drm_device \*);245Those are legacy suspend and resume methods which *only* work with the246legacy shadow-attach driver registration functions. New driver should247use the power management interface provided by their bus type (usually248through the :c:type:`struct device_driver <device_driver>`249dev_pm_ops) and set these methods to NULL.250 251Legacy DMA Services252-------------------253 254This should cover how DMA mapping etc. is supported by the core. These255functions are deprecated and should not be used.256