]>
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 | |
27 | :c:func:`drm_dev_alloc()` to allocate a device instance. After the | |
28 | device instance is fully initialized it can be registered (which makes | |
29 | it accessible from userspace) using :c:func:`drm_dev_register()`. | |
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 JN |
41 | |
42 | Driver Features | |
2fa91d15 | 43 | ~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
44 | |
45 | Drivers inform the DRM core about their requirements and supported | |
46 | features by setting appropriate flags in the driver_features field. | |
47 | Since those flags influence the DRM core behaviour since registration | |
48 | time, most of them must be set to registering the :c:type:`struct | |
49 | drm_driver <drm_driver>` instance. | |
50 | ||
51 | u32 driver_features; | |
52 | ||
53 | DRIVER_USE_AGP | |
54 | Driver uses AGP interface, the DRM core will manage AGP resources. | |
55 | ||
3cbf6a5d DV |
56 | DRIVER_LEGACY |
57 | Denote a legacy driver using shadow attach. Don't use. | |
58 | ||
59 | DRIVER_KMS_LEGACY_CONTEXT | |
60 | Used only by nouveau for backwards compatibility with existing userspace. | |
61 | Don't use. | |
ca00c2b9 JN |
62 | |
63 | DRIVER_PCI_DMA | |
64 | Driver is capable of PCI DMA, mapping of PCI DMA buffers to | |
65 | userspace will be enabled. Deprecated. | |
66 | ||
67 | DRIVER_SG | |
68 | Driver can perform scatter/gather DMA, allocation and mapping of | |
69 | scatter/gather buffers will be enabled. Deprecated. | |
70 | ||
71 | DRIVER_HAVE_DMA | |
72 | Driver supports DMA, the userspace DMA API will be supported. | |
73 | Deprecated. | |
74 | ||
75 | DRIVER_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 | ||
84 | DRIVER_GEM | |
85 | Driver use the GEM memory manager. | |
86 | ||
87 | DRIVER_MODESET | |
88 | Driver supports mode setting interfaces (KMS). | |
89 | ||
90 | DRIVER_PRIME | |
91 | Driver implements DRM PRIME buffer sharing. | |
92 | ||
93 | DRIVER_RENDER | |
94 | Driver supports dedicated render nodes. | |
95 | ||
96 | DRIVER_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 | ||
101 | Major, Minor and Patchlevel | |
2fa91d15 | 102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
103 | |
104 | int major; int minor; int patchlevel; | |
105 | The DRM core identifies driver versions by a major, minor and patch | |
106 | level triplet. The information is printed to the kernel log at | |
107 | initialization time and passed to userspace through the | |
108 | DRM_IOCTL_VERSION ioctl. | |
109 | ||
110 | The major and minor numbers are also used to verify the requested driver | |
111 | API version passed to DRM_IOCTL_SET_VERSION. When the driver API | |
112 | changes between minor versions, applications can call | |
113 | DRM_IOCTL_SET_VERSION to select a specific version of the API. If the | |
114 | requested major isn't equal to the driver major, or the requested minor | |
115 | is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will | |
116 | return an error. Otherwise the driver's set_version() method will be | |
117 | called with the requested version. | |
118 | ||
119 | Name, Description and Date | |
2fa91d15 | 120 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
121 | |
122 | char \*name; char \*desc; char \*date; | |
123 | The driver name is printed to the kernel log at initialization time, | |
124 | used for IRQ registration and passed to userspace through | |
125 | DRM_IOCTL_VERSION. | |
126 | ||
127 | The driver description is a purely informative string passed to | |
128 | userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by | |
129 | the kernel. | |
130 | ||
131 | The driver date, formatted as YYYYMMDD, is meant to identify the date of | |
132 | the latest modification to the driver. However, as most drivers fail to | |
133 | update it, its value is mostly useless. The DRM core prints it to the | |
134 | kernel log at initialization time and passes it to userspace through the | |
135 | DRM_IOCTL_VERSION ioctl. | |
136 | ||
137 | Device Instance and Driver Handling | |
22554020 | 138 | ----------------------------------- |
ca00c2b9 JN |
139 | |
140 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c | |
141 | :doc: driver instance overview | |
142 | ||
6c4789ed DV |
143 | .. kernel-doc:: include/drm/drm_drv.h |
144 | :internal: | |
145 | ||
1ea35768 DV |
146 | .. kernel-doc:: drivers/gpu/drm/drm_drv.c |
147 | :export: | |
148 | ||
ca00c2b9 | 149 | Driver Load |
22554020 | 150 | ----------- |
ca00c2b9 JN |
151 | |
152 | IRQ Registration | |
2fa91d15 | 153 | ~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
154 | |
155 | The DRM core tries to facilitate IRQ handler registration and | |
156 | unregistration by providing :c:func:`drm_irq_install()` and | |
157 | :c:func:`drm_irq_uninstall()` functions. Those functions only | |
158 | support a single interrupt per device, devices that use more than one | |
159 | IRQs need to be handled manually. | |
160 | ||
161 | Managed IRQ Registration | |
162 | '''''''''''''''''''''''' | |
163 | ||
164 | :c:func:`drm_irq_install()` starts by calling the irq_preinstall | |
165 | driver operation. The operation is optional and must make sure that the | |
166 | interrupt will not get fired by clearing all pending interrupt flags or | |
167 | disabling the interrupt. | |
168 | ||
169 | The passed-in IRQ will then be requested by a call to | |
170 | :c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature | |
171 | flag is set, a shared (IRQF_SHARED) IRQ handler will be requested. | |
172 | ||
173 | The IRQ handler function must be provided as the mandatory irq_handler | |
174 | driver operation. It will get passed directly to | |
175 | :c:func:`request_irq()` and thus has the same prototype as all IRQ | |
176 | handlers. It will get called with a pointer to the DRM device as the | |
177 | second argument. | |
178 | ||
179 | Finally the function calls the optional irq_postinstall driver | |
180 | operation. The operation usually enables interrupts (excluding the | |
181 | vblank interrupt, which is enabled separately), but drivers may choose | |
182 | to enable/disable interrupts at a different time. | |
183 | ||
184 | :c:func:`drm_irq_uninstall()` is similarly used to uninstall an | |
185 | IRQ handler. It starts by waking up all processes waiting on a vblank | |
186 | interrupt to make sure they don't hang, and then calls the optional | |
187 | irq_uninstall driver operation. The operation must disable all hardware | |
188 | interrupts. Finally the function frees the IRQ by calling | |
189 | :c:func:`free_irq()`. | |
190 | ||
191 | Manual IRQ Registration | |
192 | ''''''''''''''''''''''' | |
193 | ||
194 | Drivers that require multiple interrupt handlers can't use the managed | |
195 | IRQ registration functions. In that case IRQs must be registered and | |
196 | unregistered manually (usually with the :c:func:`request_irq()` and | |
a9eaa996 DV |
197 | :c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and |
198 | :c:func:`devm_free_irq()` equivalents). | |
ca00c2b9 JN |
199 | |
200 | When manually registering IRQs, drivers must not set the | |
201 | DRIVER_HAVE_IRQ driver feature flag, and must not provide the | |
202 | irq_handler driver operation. They must set the :c:type:`struct | |
203 | drm_device <drm_device>` irq_enabled field to 1 upon | |
204 | registration of the IRQs, and clear it to 0 after unregistering the | |
205 | IRQs. | |
206 | ||
207 | Memory Manager Initialization | |
2fa91d15 | 208 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
209 | |
210 | Every DRM driver requires a memory manager which must be initialized at | |
211 | load time. DRM currently contains two memory managers, the Translation | |
212 | Table Manager (TTM) and the Graphics Execution Manager (GEM). This | |
213 | document describes the use of the GEM memory manager only. See ? for | |
214 | details. | |
215 | ||
216 | Miscellaneous Device Configuration | |
2fa91d15 | 217 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 JN |
218 | |
219 | Another task that may be necessary for PCI devices during configuration | |
220 | is mapping the video BIOS. On many devices, the VBIOS describes device | |
221 | configuration, LCD panel timings (if any), and contains flags indicating | |
222 | device state. Mapping the BIOS can be done using the pci_map_rom() | |
223 | call, a convenience function that takes care of mapping the actual ROM, | |
224 | whether it has been shadowed into memory (typically at address 0xc0000) | |
225 | or exists on the PCI device in the ROM BAR. Note that after the ROM has | |
226 | been mapped and any necessary information has been extracted, it should | |
227 | be unmapped; on many devices, the ROM address decoder is shared with | |
228 | other BARs, so leaving it mapped could cause undesired behaviour like | |
229 | hangs or memory corruption. | |
230 | ||
231 | Bus-specific Device Registration and PCI Support | |
22554020 | 232 | ------------------------------------------------ |
ca00c2b9 JN |
233 | |
234 | A number of functions are provided to help with device registration. The | |
235 | functions deal with PCI and platform devices respectively and are only | |
236 | provided for historical reasons. These are all deprecated and shouldn't | |
237 | be used in new drivers. Besides that there's a few helpers for pci | |
238 | drivers. | |
239 | ||
240 | .. kernel-doc:: drivers/gpu/drm/drm_pci.c | |
241 | :export: | |
242 | ||
ca00c2b9 | 243 | Open/Close, File Operations and IOCTLs |
22554020 | 244 | ====================================== |
ca00c2b9 | 245 | |
ca00c2b9 | 246 | File Operations |
22554020 | 247 | --------------- |
ca00c2b9 | 248 | |
9acdac68 | 249 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
ca00c2b9 JN |
250 | :doc: file operations |
251 | ||
b93658f8 DV |
252 | .. kernel-doc:: include/drm/drm_file.h |
253 | :internal: | |
254 | ||
9acdac68 | 255 | .. kernel-doc:: drivers/gpu/drm/drm_file.c |
ca00c2b9 JN |
256 | :export: |
257 | ||
d8187177 RC |
258 | Misc Utilities |
259 | ============== | |
260 | ||
261 | Printer | |
262 | ------- | |
263 | ||
264 | .. kernel-doc:: include/drm/drm_print.h | |
265 | :doc: print | |
266 | ||
267 | .. kernel-doc:: include/drm/drm_print.h | |
268 | :internal: | |
269 | ||
2d5e836d | 270 | .. kernel-doc:: drivers/gpu/drm/drm_print.c |
d8187177 RC |
271 | :export: |
272 | ||
273 | ||
ca00c2b9 | 274 | Legacy Support Code |
22554020 | 275 | =================== |
ca00c2b9 JN |
276 | |
277 | The section very briefly covers some of the old legacy support code | |
278 | which is only used by old DRM drivers which have done a so-called | |
279 | shadow-attach to the underlying device instead of registering as a real | |
280 | driver. This also includes some of the old generic buffer management and | |
281 | command submission code. Do not use any of this in new and modern | |
282 | drivers. | |
283 | ||
284 | Legacy Suspend/Resume | |
22554020 | 285 | --------------------- |
ca00c2b9 JN |
286 | |
287 | The DRM core provides some suspend/resume code, but drivers wanting full | |
288 | suspend/resume support should provide save() and restore() functions. | |
289 | These are called at suspend, hibernate, or resume time, and should | |
290 | perform any state save or restore required by your device across suspend | |
291 | or hibernate states. | |
292 | ||
293 | int (\*suspend) (struct drm_device \*, pm_message_t state); int | |
294 | (\*resume) (struct drm_device \*); | |
295 | Those are legacy suspend and resume methods which *only* work with the | |
296 | legacy shadow-attach driver registration functions. New driver should | |
297 | use the power management interface provided by their bus type (usually | |
298 | through the :c:type:`struct device_driver <device_driver>` | |
299 | dev_pm_ops) and set these methods to NULL. | |
300 | ||
301 | Legacy DMA Services | |
22554020 | 302 | ------------------- |
ca00c2b9 JN |
303 | |
304 | This should cover how DMA mapping etc. is supported by the core. These | |
305 | functions are deprecated and should not be used. |