blob: 37284bcc77641a76d9b658fb30c50e2bde861542 [file] [log] [blame]
Jani Nikula22554022016-06-21 14:49:00 +03001=============
Jani Nikulaca00c2b2016-06-21 14:48:58 +03002DRM 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
Jani Nikula22554022016-06-21 14:49:00 +030022=====================
Jani Nikulaca00c2b2016-06-21 14:48:58 +030023
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
Jani Nikula22554022016-06-21 14:49:00 +030040------------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +030041
42Driver Features
Jani Nikula2fa91d12016-06-21 14:49:02 +030043~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +030044
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
Daniel Vetter3cbf6a52016-08-03 21:11:09 +020056DRIVER_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.
Jani Nikulaca00c2b2016-06-21 14:48:58 +030062
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
Jani Nikula2fa91d12016-06-21 14:49:02 +0300102~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300103
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
Jani Nikula2fa91d12016-06-21 14:49:02 +0300120~~~~~~~~~~~~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300121
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
Jani Nikula22554022016-06-21 14:49:00 +0300138-----------------------------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300139
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
146Driver Load
Jani Nikula22554022016-06-21 14:49:00 +0300147-----------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300148
149IRQ Registration
Jani Nikula2fa91d12016-06-21 14:49:02 +0300150~~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300151
152The DRM core tries to facilitate IRQ handler registration and
153unregistration by providing :c:func:`drm_irq_install()` and
154:c:func:`drm_irq_uninstall()` functions. Those functions only
155support a single interrupt per device, devices that use more than one
156IRQs need to be handled manually.
157
158Managed IRQ Registration
159''''''''''''''''''''''''
160
161:c:func:`drm_irq_install()` starts by calling the irq_preinstall
162driver operation. The operation is optional and must make sure that the
163interrupt will not get fired by clearing all pending interrupt flags or
164disabling the interrupt.
165
166The passed-in IRQ will then be requested by a call to
167:c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature
168flag is set, a shared (IRQF_SHARED) IRQ handler will be requested.
169
170The IRQ handler function must be provided as the mandatory irq_handler
171driver operation. It will get passed directly to
172:c:func:`request_irq()` and thus has the same prototype as all IRQ
173handlers. It will get called with a pointer to the DRM device as the
174second argument.
175
176Finally the function calls the optional irq_postinstall driver
177operation. The operation usually enables interrupts (excluding the
178vblank interrupt, which is enabled separately), but drivers may choose
179to enable/disable interrupts at a different time.
180
181:c:func:`drm_irq_uninstall()` is similarly used to uninstall an
182IRQ handler. It starts by waking up all processes waiting on a vblank
183interrupt to make sure they don't hang, and then calls the optional
184irq_uninstall driver operation. The operation must disable all hardware
185interrupts. Finally the function frees the IRQ by calling
186:c:func:`free_irq()`.
187
188Manual IRQ Registration
189'''''''''''''''''''''''
190
191Drivers that require multiple interrupt handlers can't use the managed
192IRQ registration functions. In that case IRQs must be registered and
193unregistered manually (usually with the :c:func:`request_irq()` and
Daniel Vettera9eaa992016-07-15 21:48:08 +0200194:c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and
195:c:func:`devm_free_irq()` equivalents).
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300196
197When manually registering IRQs, drivers must not set the
198DRIVER_HAVE_IRQ driver feature flag, and must not provide the
199irq_handler driver operation. They must set the :c:type:`struct
200drm_device <drm_device>` irq_enabled field to 1 upon
201registration of the IRQs, and clear it to 0 after unregistering the
202IRQs.
203
204Memory Manager Initialization
Jani Nikula2fa91d12016-06-21 14:49:02 +0300205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300206
207Every DRM driver requires a memory manager which must be initialized at
208load time. DRM currently contains two memory managers, the Translation
209Table Manager (TTM) and the Graphics Execution Manager (GEM). This
210document describes the use of the GEM memory manager only. See ? for
211details.
212
213Miscellaneous Device Configuration
Jani Nikula2fa91d12016-06-21 14:49:02 +0300214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300215
216Another task that may be necessary for PCI devices during configuration
217is mapping the video BIOS. On many devices, the VBIOS describes device
218configuration, LCD panel timings (if any), and contains flags indicating
219device state. Mapping the BIOS can be done using the pci_map_rom()
220call, a convenience function that takes care of mapping the actual ROM,
221whether it has been shadowed into memory (typically at address 0xc0000)
222or exists on the PCI device in the ROM BAR. Note that after the ROM has
223been mapped and any necessary information has been extracted, it should
224be unmapped; on many devices, the ROM address decoder is shared with
225other BARs, so leaving it mapped could cause undesired behaviour like
226hangs or memory corruption.
227
228Bus-specific Device Registration and PCI Support
Jani Nikula22554022016-06-21 14:49:00 +0300229------------------------------------------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300230
231A number of functions are provided to help with device registration. The
232functions deal with PCI and platform devices respectively and are only
233provided for historical reasons. These are all deprecated and shouldn't
234be used in new drivers. Besides that there's a few helpers for pci
235drivers.
236
237.. kernel-doc:: drivers/gpu/drm/drm_pci.c
238 :export:
239
240.. kernel-doc:: drivers/gpu/drm/drm_platform.c
241 :export:
242
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300243Open/Close, File Operations and IOCTLs
Jani Nikula22554022016-06-21 14:49:00 +0300244======================================
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300245
246Open and Close
Jani Nikula22554022016-06-21 14:49:00 +0300247--------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300248
Daniel Vettera9eaa992016-07-15 21:48:08 +0200249Open and close handlers. None of those methods are mandatory::
250
251 int (*firstopen) (struct drm_device *);
252 void (*lastclose) (struct drm_device *);
253 int (*open) (struct drm_device *, struct drm_file *);
254 void (*preclose) (struct drm_device *, struct drm_file *);
255 void (*postclose) (struct drm_device *, struct drm_file *);
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300256
257The firstopen method is called by the DRM core for legacy UMS (User Mode
258Setting) drivers only when an application opens a device that has no
259other opened file handle. UMS drivers can implement it to acquire device
260resources. KMS drivers can't use the method and must acquire resources
261in the load method instead.
262
263Similarly the lastclose method is called when the last application
264holding a file handle opened on the device closes it, for both UMS and
265KMS drivers. Additionally, the method is also called at module unload
266time or, for hot-pluggable devices, when the device is unplugged. The
267firstopen and lastclose calls can thus be unbalanced.
268
269The open method is called every time the device is opened by an
270application. Drivers can allocate per-file private data in this method
271and store them in the struct :c:type:`struct drm_file
272<drm_file>` driver_priv field. Note that the open method is
273called before firstopen.
274
275The close operation is split into preclose and postclose methods.
276Drivers must stop and cleanup all per-file operations in the preclose
277method. For instance pending vertical blanking and page flip events must
278be cancelled. No per-file operation is allowed on the file handle after
279returning from the preclose method.
280
281Finally the postclose method is called as the last step of the close
282operation, right before calling the lastclose method if no other open
283file handle exists for the device. Drivers that have allocated per-file
284private data in the open method should free it here.
285
286The lastclose method should restore CRTC and plane properties to default
287value, so that a subsequent open of the device will not inherit state
288from the previous user. It can also be used to execute delayed power
Lukas Wunnerfb001df2016-07-11 10:22:33 +0200289switching state changes, e.g. in conjunction with the :ref:`vga_switcheroo`
290infrastructure. Beyond that KMS drivers should not do any
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300291further cleanup. Only legacy UMS drivers might need to clean up device
292state so that the vga console or an independent fbdev driver could take
293over.
294
295File Operations
Jani Nikula22554022016-06-21 14:49:00 +0300296---------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300297
298.. kernel-doc:: drivers/gpu/drm/drm_fops.c
299 :doc: file operations
300
301.. kernel-doc:: drivers/gpu/drm/drm_fops.c
302 :export:
303
304IOCTLs
Jani Nikula22554022016-06-21 14:49:00 +0300305------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300306
307struct drm_ioctl_desc \*ioctls; int num_ioctls;
308 Driver-specific ioctls descriptors table.
309
310Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
311descriptors table is indexed by the ioctl number offset from the base
312value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize
313the table entries.
314
315::
316
317 DRM_IOCTL_DEF_DRV(ioctl, func, flags)
318
319``ioctl`` is the ioctl name. Drivers must define the DRM_##ioctl and
320DRM_IOCTL_##ioctl macros to the ioctl number offset from
321DRM_COMMAND_BASE and the ioctl number respectively. The first macro is
322private to the device while the second must be exposed to userspace in a
323public header.
324
325``func`` is a pointer to the ioctl handler function compatible with the
326``drm_ioctl_t`` type.
327
328::
329
330 typedef int drm_ioctl_t(struct drm_device *dev, void *data,
331 struct drm_file *file_priv);
332
333``flags`` is a bitmask combination of the following values. It restricts
334how the ioctl is allowed to be called.
335
336- DRM_AUTH - Only authenticated callers allowed
337
338- DRM_MASTER - The ioctl can only be called on the master file handle
339
340- DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
341
342- DRM_CONTROL_ALLOW - The ioctl can only be called on a control
343 device
344
345- DRM_UNLOCKED - The ioctl handler will be called without locking the
346 DRM global mutex. This is the enforced default for kms drivers (i.e.
347 using the DRIVER_MODESET flag) and hence shouldn't be used any more
348 for new drivers.
349
350.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
351 :export:
352
353Legacy Support Code
Jani Nikula22554022016-06-21 14:49:00 +0300354===================
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300355
356The section very briefly covers some of the old legacy support code
357which is only used by old DRM drivers which have done a so-called
358shadow-attach to the underlying device instead of registering as a real
359driver. This also includes some of the old generic buffer management and
360command submission code. Do not use any of this in new and modern
361drivers.
362
363Legacy Suspend/Resume
Jani Nikula22554022016-06-21 14:49:00 +0300364---------------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300365
366The DRM core provides some suspend/resume code, but drivers wanting full
367suspend/resume support should provide save() and restore() functions.
368These are called at suspend, hibernate, or resume time, and should
369perform any state save or restore required by your device across suspend
370or hibernate states.
371
372int (\*suspend) (struct drm_device \*, pm_message_t state); int
373(\*resume) (struct drm_device \*);
374Those are legacy suspend and resume methods which *only* work with the
375legacy shadow-attach driver registration functions. New driver should
376use the power management interface provided by their bus type (usually
377through the :c:type:`struct device_driver <device_driver>`
378dev_pm_ops) and set these methods to NULL.
379
380Legacy DMA Services
Jani Nikula22554022016-06-21 14:49:00 +0300381-------------------
Jani Nikulaca00c2b2016-06-21 14:48:58 +0300382
383This should cover how DMA mapping etc. is supported by the core. These
384functions are deprecated and should not be used.