Commit | Line | Data |
---|---|---|
22554020 | 1 | ============= |
ca00c2b9 JN |
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 | |
22554020 | 22 | ===================== |
ca00c2b9 JN |
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 | |
6acc942c | 27 | drm_dev_alloc() to allocate a device instance. After the |
ca00c2b9 | 28 | device instance is fully initialized it can be registered (which makes |
6acc942c | 29 | it accessible from userspace) using drm_dev_register(). |
ca00c2b9 JN |
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 | |
22554020 | 40 | ------------------ |
ca00c2b9 | 41 | |
ca00c2b9 | 42 | Major, Minor and Patchlevel |
2fa91d15 | 43 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
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 | |
2fa91d15 | 61 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
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 | ||
52506b09 TZ |
78 | Module Initialization |
79 | --------------------- | |
80 | ||
81 | .. kernel-doc:: include/drm/drm_module.h | |
82 | :doc: overview | |
83 | ||
29160591 TZ |
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 | ||
ca00c2b9 | 96 | Device Instance and Driver Handling |
22554020 | 97 | ----------------------------------- |
ca00c2b9 JN |
98 | |
99 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c | |
100 | :doc: driver instance overview | |
101 | ||
3214a166 DV |
102 | .. kernel-doc:: include/drm/drm_device.h |
103 | :internal: | |
104 | ||
6c4789ed DV |
105 | .. kernel-doc:: include/drm/drm_drv.h |
106 | :internal: | |
107 | ||
1ea35768 DV |
108 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c |
109 | :export: | |
110 | ||
ca00c2b9 | 111 | Driver Load |
22554020 | 112 | ----------- |
ca00c2b9 | 113 | |
86ab67df DV |
114 | Component Helper Usage |
115 | ~~~~~~~~~~~~~~~~~~~~~~ | |
116 | ||
117 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c | |
118 | :doc: component helper usage recommendations | |
ca00c2b9 JN |
119 | |
120 | Memory Manager Initialization | |
2fa91d15 | 121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
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 | |
2fa91d15 | 130 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
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 | ||
c6603c74 DV |
144 | Managed Resources |
145 | ----------------- | |
146 | ||
147 | .. kernel-doc:: drivers/gpu/drm/drm_managed.c | |
148 | :doc: managed resources | |
149 | ||
9e1ed9fb DV |
150 | .. kernel-doc:: drivers/gpu/drm/drm_managed.c |
151 | :export: | |
152 | ||
153 | .. kernel-doc:: include/drm/drm_managed.h | |
154 | :internal: | |
155 | ||
ca00c2b9 | 156 | Bus-specific Device Registration and PCI Support |
22554020 | 157 | ------------------------------------------------ |
ca00c2b9 JN |
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 | ||
ca00c2b9 | 168 | Open/Close, File Operations and IOCTLs |
22554020 | 169 | ====================================== |
ca00c2b9 | 170 | |
bb2eaba6 DV |
171 | .. _drm_driver_fops: |
172 | ||
ca00c2b9 | 173 | File Operations |
22554020 | 174 | --------------- |
ca00c2b9 | 175 | |
9acdac68 | 176 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
ca00c2b9 JN |
177 | :doc: file operations |
178 | ||
b93658f8 DV |
179 | .. kernel-doc:: include/drm/drm_file.h |
180 | :internal: | |
181 | ||
9acdac68 | 182 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
ca00c2b9 JN |
183 | :export: |
184 | ||
d8187177 RC |
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 | ||
2d5e836d | 197 | .. kernel-doc:: drivers/gpu/drm/drm_print.c |
d8187177 RC |
198 | :export: |
199 | ||
e9eafcb5 SR |
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 | ||
d8187177 | 209 | |
6fde8eec JE |
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 | ||
ca00c2b9 | 242 | Legacy Support Code |
22554020 | 243 | =================== |
ca00c2b9 JN |
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 | |
22554020 | 253 | --------------------- |
ca00c2b9 JN |
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 | |
22554020 | 270 | ------------------- |
ca00c2b9 JN |
271 | |
272 | This should cover how DMA mapping etc. is supported by the core. These | |
273 | functions are deprecated and should not be used. |