Loading...
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
101Major, Minor and Patchlevel
102~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
104int major; int minor; int patchlevel;
105The DRM core identifies driver versions by a major, minor and patch
106level triplet. The information is printed to the kernel log at
107initialization time and passed to userspace through the
108DRM_IOCTL_VERSION ioctl.
109
110The major and minor numbers are also used to verify the requested driver
111API version passed to DRM_IOCTL_SET_VERSION. When the driver API
112changes between minor versions, applications can call
113DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
114requested major isn't equal to the driver major, or the requested minor
115is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
116return an error. Otherwise the driver's set_version() method will be
117called with the requested version.
118
119Name, Description and Date
120~~~~~~~~~~~~~~~~~~~~~~~~~~
121
122char \*name; char \*desc; char \*date;
123The driver name is printed to the kernel log at initialization time,
124used for IRQ registration and passed to userspace through
125DRM_IOCTL_VERSION.
126
127The driver description is a purely informative string passed to
128userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
129the kernel.
130
131The driver date, formatted as YYYYMMDD, is meant to identify the date of
132the latest modification to the driver. However, as most drivers fail to
133update it, its value is mostly useless. The DRM core prints it to the
134kernel log at initialization time and passes it to userspace through the
135DRM_IOCTL_VERSION ioctl.
136
137Device Instance and Driver Handling
138-----------------------------------
139
140.. kernel-doc:: drivers/gpu/drm/drm_drv.c
141 :doc: driver instance overview
142
143.. kernel-doc:: drivers/gpu/drm/drm_drv.c
144 :export:
145
146.. kernel-doc:: include/drm/drm_drv.h
147 :internal:
148
149Driver Load
150-----------
151
152IRQ Registration
153~~~~~~~~~~~~~~~~
154
155The DRM core tries to facilitate IRQ handler registration and
156unregistration by providing :c:func:`drm_irq_install()` and
157:c:func:`drm_irq_uninstall()` functions. Those functions only
158support a single interrupt per device, devices that use more than one
159IRQs need to be handled manually.
160
161Managed IRQ Registration
162''''''''''''''''''''''''
163
164:c:func:`drm_irq_install()` starts by calling the irq_preinstall
165driver operation. The operation is optional and must make sure that the
166interrupt will not get fired by clearing all pending interrupt flags or
167disabling the interrupt.
168
169The passed-in IRQ will then be requested by a call to
170:c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature
171flag is set, a shared (IRQF_SHARED) IRQ handler will be requested.
172
173The IRQ handler function must be provided as the mandatory irq_handler
174driver operation. It will get passed directly to
175:c:func:`request_irq()` and thus has the same prototype as all IRQ
176handlers. It will get called with a pointer to the DRM device as the
177second argument.
178
179Finally the function calls the optional irq_postinstall driver
180operation. The operation usually enables interrupts (excluding the
181vblank interrupt, which is enabled separately), but drivers may choose
182to enable/disable interrupts at a different time.
183
184:c:func:`drm_irq_uninstall()` is similarly used to uninstall an
185IRQ handler. It starts by waking up all processes waiting on a vblank
186interrupt to make sure they don't hang, and then calls the optional
187irq_uninstall driver operation. The operation must disable all hardware
188interrupts. Finally the function frees the IRQ by calling
189:c:func:`free_irq()`.
190
191Manual IRQ Registration
192'''''''''''''''''''''''
193
194Drivers that require multiple interrupt handlers can't use the managed
195IRQ registration functions. In that case IRQs must be registered and
196unregistered manually (usually with the :c:func:`request_irq()` and
197:c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and
198:c:func:`devm_free_irq()` equivalents).
199
200When manually registering IRQs, drivers must not set the
201DRIVER_HAVE_IRQ driver feature flag, and must not provide the
202irq_handler driver operation. They must set the :c:type:`struct
203drm_device <drm_device>` irq_enabled field to 1 upon
204registration of the IRQs, and clear it to 0 after unregistering the
205IRQs.
206
207Memory Manager Initialization
208~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209
210Every DRM driver requires a memory manager which must be initialized at
211load time. DRM currently contains two memory managers, the Translation
212Table Manager (TTM) and the Graphics Execution Manager (GEM). This
213document describes the use of the GEM memory manager only. See ? for
214details.
215
216Miscellaneous Device Configuration
217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
218
219Another task that may be necessary for PCI devices during configuration
220is mapping the video BIOS. On many devices, the VBIOS describes device
221configuration, LCD panel timings (if any), and contains flags indicating
222device state. Mapping the BIOS can be done using the pci_map_rom()
223call, a convenience function that takes care of mapping the actual ROM,
224whether it has been shadowed into memory (typically at address 0xc0000)
225or exists on the PCI device in the ROM BAR. Note that after the ROM has
226been mapped and any necessary information has been extracted, it should
227be unmapped; on many devices, the ROM address decoder is shared with
228other BARs, so leaving it mapped could cause undesired behaviour like
229hangs or memory corruption.
230
231Bus-specific Device Registration and PCI Support
232------------------------------------------------
233
234A number of functions are provided to help with device registration. The
235functions deal with PCI and platform devices respectively and are only
236provided for historical reasons. These are all deprecated and shouldn't
237be used in new drivers. Besides that there's a few helpers for pci
238drivers.
239
240.. kernel-doc:: drivers/gpu/drm/drm_pci.c
241 :export:
242
243.. kernel-doc:: drivers/gpu/drm/drm_platform.c
244 :export:
245
246Open/Close, File Operations and IOCTLs
247======================================
248
249Open and Close
250--------------
251
252Open and close handlers. None of those methods are mandatory::
253
254 int (*firstopen) (struct drm_device *);
255 void (*lastclose) (struct drm_device *);
256 int (*open) (struct drm_device *, struct drm_file *);
257 void (*preclose) (struct drm_device *, struct drm_file *);
258 void (*postclose) (struct drm_device *, struct drm_file *);
259
260The firstopen method is called by the DRM core for legacy UMS (User Mode
261Setting) drivers only when an application opens a device that has no
262other opened file handle. UMS drivers can implement it to acquire device
263resources. KMS drivers can't use the method and must acquire resources
264in the load method instead.
265
266Similarly the lastclose method is called when the last application
267holding a file handle opened on the device closes it, for both UMS and
268KMS drivers. Additionally, the method is also called at module unload
269time or, for hot-pluggable devices, when the device is unplugged. The
270firstopen and lastclose calls can thus be unbalanced.
271
272The open method is called every time the device is opened by an
273application. Drivers can allocate per-file private data in this method
274and store them in the struct :c:type:`struct drm_file
275<drm_file>` driver_priv field. Note that the open method is
276called before firstopen.
277
278The close operation is split into preclose and postclose methods.
279Drivers must stop and cleanup all per-file operations in the preclose
280method. For instance pending vertical blanking and page flip events must
281be cancelled. No per-file operation is allowed on the file handle after
282returning from the preclose method.
283
284Finally the postclose method is called as the last step of the close
285operation, right before calling the lastclose method if no other open
286file handle exists for the device. Drivers that have allocated per-file
287private data in the open method should free it here.
288
289The lastclose method should restore CRTC and plane properties to default
290value, so that a subsequent open of the device will not inherit state
291from the previous user. It can also be used to execute delayed power
292switching state changes, e.g. in conjunction with the :ref:`vga_switcheroo`
293infrastructure. Beyond that KMS drivers should not do any
294further cleanup. Only legacy UMS drivers might need to clean up device
295state so that the vga console or an independent fbdev driver could take
296over.
297
298File Operations
299---------------
300
301.. kernel-doc:: drivers/gpu/drm/drm_fops.c
302 :doc: file operations
303
304.. kernel-doc:: drivers/gpu/drm/drm_fops.c
305 :export:
306
307IOCTLs
308------
309
310struct drm_ioctl_desc \*ioctls; int num_ioctls;
311 Driver-specific ioctls descriptors table.
312
313Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
314descriptors table is indexed by the ioctl number offset from the base
315value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize
316the table entries.
317
318::
319
320 DRM_IOCTL_DEF_DRV(ioctl, func, flags)
321
322``ioctl`` is the ioctl name. Drivers must define the DRM_##ioctl and
323DRM_IOCTL_##ioctl macros to the ioctl number offset from
324DRM_COMMAND_BASE and the ioctl number respectively. The first macro is
325private to the device while the second must be exposed to userspace in a
326public header.
327
328``func`` is a pointer to the ioctl handler function compatible with the
329``drm_ioctl_t`` type.
330
331::
332
333 typedef int drm_ioctl_t(struct drm_device *dev, void *data,
334 struct drm_file *file_priv);
335
336``flags`` is a bitmask combination of the following values. It restricts
337how the ioctl is allowed to be called.
338
339- DRM_AUTH - Only authenticated callers allowed
340
341- DRM_MASTER - The ioctl can only be called on the master file handle
342
343- DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
344
345- DRM_CONTROL_ALLOW - The ioctl can only be called on a control
346 device
347
348- DRM_UNLOCKED - The ioctl handler will be called without locking the
349 DRM global mutex. This is the enforced default for kms drivers (i.e.
350 using the DRIVER_MODESET flag) and hence shouldn't be used any more
351 for new drivers.
352
353.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
354 :export:
355
356
357Misc Utilities
358==============
359
360Printer
361-------
362
363.. kernel-doc:: include/drm/drm_print.h
364 :doc: print
365
366.. kernel-doc:: include/drm/drm_print.h
367 :internal:
368
369.. kernel-doc:: drivers/gpu/drm/drm_print.c
370 :export:
371
372
373Legacy Support Code
374===================
375
376The section very briefly covers some of the old legacy support code
377which is only used by old DRM drivers which have done a so-called
378shadow-attach to the underlying device instead of registering as a real
379driver. This also includes some of the old generic buffer management and
380command submission code. Do not use any of this in new and modern
381drivers.
382
383Legacy Suspend/Resume
384---------------------
385
386The DRM core provides some suspend/resume code, but drivers wanting full
387suspend/resume support should provide save() and restore() functions.
388These are called at suspend, hibernate, or resume time, and should
389perform any state save or restore required by your device across suspend
390or hibernate states.
391
392int (\*suspend) (struct drm_device \*, pm_message_t state); int
393(\*resume) (struct drm_device \*);
394Those are legacy suspend and resume methods which *only* work with the
395legacy shadow-attach driver registration functions. New driver should
396use the power management interface provided by their bus type (usually
397through the :c:type:`struct device_driver <device_driver>`
398dev_pm_ops) and set these methods to NULL.
399
400Legacy DMA Services
401-------------------
402
403This should cover how DMA mapping etc. is supported by the core. These
404functions are deprecated and should not be used.
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
27drm_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 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
42Major, Minor and Patchlevel
43~~~~~~~~~~~~~~~~~~~~~~~~~~~
44
45int major; int minor; int patchlevel;
46The DRM core identifies driver versions by a major, minor and patch
47level triplet. The information is printed to the kernel log at
48initialization time and passed to userspace through the
49DRM_IOCTL_VERSION ioctl.
50
51The major and minor numbers are also used to verify the requested driver
52API version passed to DRM_IOCTL_SET_VERSION. When the driver API
53changes between minor versions, applications can call
54DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
55requested major isn't equal to the driver major, or the requested minor
56is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
57return an error. Otherwise the driver's set_version() method will be
58called with the requested version.
59
60Name, Description and Date
61~~~~~~~~~~~~~~~~~~~~~~~~~~
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 through
66DRM_IOCTL_VERSION.
67
68The driver description is a purely informative string passed to
69userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
70the kernel.
71
72The driver date, formatted as YYYYMMDD, is meant to identify the date of
73the latest modification to the driver. However, as most drivers fail to
74update it, its value is mostly useless. The DRM core prints it to the
75kernel log at initialization time and passes it to userspace through the
76DRM_IOCTL_VERSION ioctl.
77
78Module Initialization
79---------------------
80
81.. kernel-doc:: include/drm/drm_module.h
82 :doc: overview
83
84Managing 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
96Device Instance and Driver Handling
97-----------------------------------
98
99.. kernel-doc:: drivers/gpu/drm/drm_drv.c
100 :doc: driver instance overview
101
102.. kernel-doc:: include/drm/drm_device.h
103 :internal:
104
105.. kernel-doc:: include/drm/drm_drv.h
106 :internal:
107
108.. kernel-doc:: drivers/gpu/drm/drm_drv.c
109 :export:
110
111Driver Load
112-----------
113
114Component Helper Usage
115~~~~~~~~~~~~~~~~~~~~~~
116
117.. kernel-doc:: drivers/gpu/drm/drm_drv.c
118 :doc: component helper usage recommendations
119
120Memory Manager Initialization
121~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122
123Every DRM driver requires a memory manager which must be initialized at
124load time. DRM currently contains two memory managers, the Translation
125Table Manager (TTM) and the Graphics Execution Manager (GEM). This
126document describes the use of the GEM memory manager only. See ? for
127details.
128
129Miscellaneous Device Configuration
130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131
132Another task that may be necessary for PCI devices during configuration
133is mapping the video BIOS. On many devices, the VBIOS describes device
134configuration, LCD panel timings (if any), and contains flags indicating
135device state. Mapping the BIOS can be done using the pci_map_rom()
136call, a convenience function that takes care of mapping the actual ROM,
137whether it has been shadowed into memory (typically at address 0xc0000)
138or exists on the PCI device in the ROM BAR. Note that after the ROM has
139been mapped and any necessary information has been extracted, it should
140be unmapped; on many devices, the ROM address decoder is shared with
141other BARs, so leaving it mapped could cause undesired behaviour like
142hangs or memory corruption.
143
144Managed Resources
145-----------------
146
147.. kernel-doc:: drivers/gpu/drm/drm_managed.c
148 :doc: managed resources
149
150.. kernel-doc:: drivers/gpu/drm/drm_managed.c
151 :export:
152
153.. kernel-doc:: include/drm/drm_managed.h
154 :internal:
155
156Bus-specific Device Registration and PCI Support
157------------------------------------------------
158
159A number of functions are provided to help with device registration. The
160functions deal with PCI and platform devices respectively and are only
161provided for historical reasons. These are all deprecated and shouldn't
162be used in new drivers. Besides that there's a few helpers for pci
163drivers.
164
165.. kernel-doc:: drivers/gpu/drm/drm_pci.c
166 :export:
167
168Open/Close, File Operations and IOCTLs
169======================================
170
171.. _drm_driver_fops:
172
173File Operations
174---------------
175
176.. kernel-doc:: drivers/gpu/drm/drm_file.c
177 :doc: file operations
178
179.. kernel-doc:: include/drm/drm_file.h
180 :internal:
181
182.. kernel-doc:: drivers/gpu/drm/drm_file.c
183 :export:
184
185Misc Utilities
186==============
187
188Printer
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
197.. kernel-doc:: drivers/gpu/drm/drm_print.c
198 :export:
199
200Utilities
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
209
210Unit testing
211============
212
213KUnit
214-----
215
216KUnit (Kernel unit testing framework) provides a common framework for unit tests
217within the Linux kernel.
218
219This section covers the specifics for the DRM subsystem. For general information
220about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.
221
222How to run the tests?
223~~~~~~~~~~~~~~~~~~~~~
224
225In order to facilitate running the test suite, a configuration file is present
226in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as
227follows:
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
242Legacy Support Code
243===================
244
245The section very briefly covers some of the old legacy support code
246which is only used by old DRM drivers which have done a so-called
247shadow-attach to the underlying device instead of registering as a real
248driver. This also includes some of the old generic buffer management and
249command submission code. Do not use any of this in new and modern
250drivers.
251
252Legacy Suspend/Resume
253---------------------
254
255The DRM core provides some suspend/resume code, but drivers wanting full
256suspend/resume support should provide save() and restore() functions.
257These are called at suspend, hibernate, or resume time, and should
258perform any state save or restore required by your device across suspend
259or hibernate states.
260
261int (\*suspend) (struct drm_device \*, pm_message_t state); int
262(\*resume) (struct drm_device \*);
263Those are legacy suspend and resume methods which *only* work with the
264legacy shadow-attach driver registration functions. New driver should
265use the power management interface provided by their bus type (usually
266through the :c:type:`struct device_driver <device_driver>`
267dev_pm_ops) and set these methods to NULL.
268
269Legacy DMA Services
270-------------------
271
272This should cover how DMA mapping etc. is supported by the core. These
273functions are deprecated and should not be used.