Commit | Line | Data |
---|---|---|
22554020 JN |
1 | =========================== |
2 | drm/i915 Intel GFX Driver | |
3 | =========================== | |
ca00c2b9 JN |
4 | |
5 | The drm/i915 driver supports all (with the exception of some very early | |
6 | models) integrated GFX chipsets with both Intel display and rendering | |
7 | blocks. This excludes a set of SoC platforms with an SGX rendering unit, | |
8 | those have basic support through the gma500 drm driver. | |
9 | ||
10 | Core Driver Infrastructure | |
22554020 | 11 | ========================== |
ca00c2b9 JN |
12 | |
13 | This section covers core driver infrastructure used by both the display | |
14 | and the GEM parts of the driver. | |
15 | ||
16 | Runtime Power Management | |
22554020 | 17 | ------------------------ |
ca00c2b9 JN |
18 | |
19 | .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c | |
20 | :doc: runtime pm | |
21 | ||
22 | .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c | |
23 | :internal: | |
24 | ||
25 | .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c | |
26 | :internal: | |
27 | ||
28 | Interrupt Handling | |
22554020 | 29 | ------------------ |
ca00c2b9 JN |
30 | |
31 | .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
32 | :doc: interrupt handling | |
33 | ||
34 | .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
35 | :functions: intel_irq_init intel_irq_init_hw intel_hpd_init | |
36 | ||
37 | .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
38 | :functions: intel_runtime_pm_disable_interrupts | |
39 | ||
40 | .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
41 | :functions: intel_runtime_pm_enable_interrupts | |
42 | ||
43 | Intel GVT-g Guest Support(vGPU) | |
22554020 | 44 | ------------------------------- |
ca00c2b9 JN |
45 | |
46 | .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c | |
47 | :doc: Intel GVT-g guest support | |
48 | ||
49 | .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c | |
50 | :internal: | |
51 | ||
22681c7b ZW |
52 | Intel GVT-g Host Support(vGPU device model) |
53 | ------------------------------------------- | |
54 | ||
55 | .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c | |
56 | :doc: Intel GVT-g host support | |
57 | ||
58 | .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c | |
59 | :internal: | |
60 | ||
7d3c425f OM |
61 | Workarounds |
62 | ----------- | |
63 | ||
bcc8737d | 64 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c |
7d3c425f OM |
65 | :doc: Hardware workarounds |
66 | ||
ca00c2b9 | 67 | Display Hardware Handling |
22554020 | 68 | ========================= |
ca00c2b9 JN |
69 | |
70 | This section covers everything related to the display hardware including | |
71 | the mode setting infrastructure, plane, sprite and cursor handling and | |
72 | display, output probing and related topics. | |
73 | ||
74 | Mode Setting Infrastructure | |
22554020 | 75 | --------------------------- |
ca00c2b9 JN |
76 | |
77 | The i915 driver is thus far the only DRM driver which doesn't use the | |
78 | common DRM helper code to implement mode setting sequences. Thus it has | |
79 | its own tailor-made infrastructure for executing a display configuration | |
80 | change. | |
81 | ||
82 | Frontbuffer Tracking | |
22554020 | 83 | -------------------- |
ca00c2b9 | 84 | |
6800d9a5 | 85 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c |
ca00c2b9 JN |
86 | :doc: frontbuffer tracking |
87 | ||
6800d9a5 | 88 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h |
5d723d7a CW |
89 | :internal: |
90 | ||
6800d9a5 | 91 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c |
ca00c2b9 JN |
92 | :internal: |
93 | ||
ca00c2b9 | 94 | Display FIFO Underrun Reporting |
22554020 | 95 | ------------------------------- |
ca00c2b9 | 96 | |
6800d9a5 | 97 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c |
ca00c2b9 JN |
98 | :doc: fifo underrun handling |
99 | ||
6800d9a5 | 100 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c |
ca00c2b9 JN |
101 | :internal: |
102 | ||
103 | Plane Configuration | |
22554020 | 104 | ------------------- |
ca00c2b9 JN |
105 | |
106 | This section covers plane configuration and composition with the primary | |
107 | plane, sprites, cursors and overlays. This includes the infrastructure | |
108 | to do atomic vsync'ed updates of all this state and also tightly coupled | |
109 | topics like watermark setup and computation, framebuffer compression and | |
110 | panel self refresh. | |
111 | ||
112 | Atomic Plane Helpers | |
22554020 | 113 | -------------------- |
ca00c2b9 | 114 | |
6800d9a5 | 115 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c |
ca00c2b9 JN |
116 | :doc: atomic plane helpers |
117 | ||
6800d9a5 | 118 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c |
ca00c2b9 JN |
119 | :internal: |
120 | ||
6914c968 K |
121 | Asynchronous Page Flip |
122 | ---------------------- | |
123 | ||
124 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c | |
125 | :doc: asynchronous flip implementation | |
126 | ||
ca00c2b9 | 127 | Output Probing |
22554020 | 128 | -------------- |
ca00c2b9 JN |
129 | |
130 | This section covers output probing and related infrastructure like the | |
131 | hotplug interrupt storm detection and mitigation code. Note that the | |
132 | i915 driver still uses most of the common DRM helper code for output | |
133 | probing, so those sections fully apply. | |
134 | ||
135 | Hotplug | |
22554020 | 136 | ------- |
ca00c2b9 | 137 | |
6800d9a5 | 138 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c |
ca00c2b9 JN |
139 | :doc: Hotplug |
140 | ||
6800d9a5 | 141 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c |
ca00c2b9 JN |
142 | :internal: |
143 | ||
144 | High Definition Audio | |
22554020 | 145 | --------------------- |
ca00c2b9 | 146 | |
6800d9a5 | 147 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c |
ca00c2b9 JN |
148 | :doc: High Definition Audio over HDMI and Display Port |
149 | ||
6800d9a5 | 150 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c |
ca00c2b9 JN |
151 | :internal: |
152 | ||
153 | .. kernel-doc:: include/drm/i915_component.h | |
154 | :internal: | |
155 | ||
eacc8daf TI |
156 | Intel HDMI LPE Audio Support |
157 | ---------------------------- | |
158 | ||
6800d9a5 | 159 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c |
eacc8daf TI |
160 | :doc: LPE Audio integration for HDMI or DP playback |
161 | ||
6800d9a5 | 162 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c |
eacc8daf TI |
163 | :internal: |
164 | ||
ca00c2b9 | 165 | Panel Self Refresh PSR (PSR/SRD) |
22554020 | 166 | -------------------------------- |
ca00c2b9 | 167 | |
6800d9a5 | 168 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c |
ca00c2b9 JN |
169 | :doc: Panel Self Refresh (PSR/SRD) |
170 | ||
6800d9a5 | 171 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c |
ca00c2b9 JN |
172 | :internal: |
173 | ||
174 | Frame Buffer Compression (FBC) | |
22554020 | 175 | ------------------------------ |
ca00c2b9 | 176 | |
6800d9a5 | 177 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c |
ca00c2b9 JN |
178 | :doc: Frame Buffer Compression (FBC) |
179 | ||
6800d9a5 | 180 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c |
ca00c2b9 JN |
181 | :internal: |
182 | ||
183 | Display Refresh Rate Switching (DRRS) | |
22554020 | 184 | ------------------------------------- |
ca00c2b9 | 185 | |
a1b63119 | 186 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c |
ca00c2b9 JN |
187 | :doc: Display Refresh Rate Switching (DRRS) |
188 | ||
a1b63119 | 189 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c |
fd048473 | 190 | :internal: |
ca00c2b9 JN |
191 | |
192 | DPIO | |
22554020 | 193 | ---- |
ca00c2b9 | 194 | |
6800d9a5 | 195 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c |
ca00c2b9 JN |
196 | :doc: DPIO |
197 | ||
32f9402d AS |
198 | DMC Firmware Support |
199 | -------------------- | |
ca00c2b9 | 200 | |
32f9402d AS |
201 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c |
202 | :doc: DMC Firmware Support | |
ca00c2b9 | 203 | |
32f9402d | 204 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c |
ca00c2b9 JN |
205 | :internal: |
206 | ||
207 | Video BIOS Table (VBT) | |
22554020 | 208 | ---------------------- |
ca00c2b9 | 209 | |
6800d9a5 | 210 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c |
ca00c2b9 JN |
211 | :doc: Video BIOS Table (VBT) |
212 | ||
6800d9a5 | 213 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c |
ca00c2b9 JN |
214 | :internal: |
215 | ||
6800d9a5 | 216 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h |
ca00c2b9 JN |
217 | :internal: |
218 | ||
7ff89ca2 VS |
219 | Display clocks |
220 | -------------- | |
221 | ||
6800d9a5 | 222 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c |
7ff89ca2 VS |
223 | :doc: CDCLK / RAWCLK |
224 | ||
6800d9a5 | 225 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c |
7ff89ca2 VS |
226 | :internal: |
227 | ||
294591cf ACO |
228 | Display PLLs |
229 | ------------ | |
230 | ||
6800d9a5 | 231 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c |
294591cf ACO |
232 | :doc: Display PLLs |
233 | ||
6800d9a5 | 234 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c |
294591cf ACO |
235 | :internal: |
236 | ||
6800d9a5 | 237 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h |
294591cf ACO |
238 | :internal: |
239 | ||
5dd85e72 AM |
240 | Display State Buffer |
241 | -------------------- | |
242 | ||
243 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c | |
244 | :doc: DSB | |
245 | ||
246 | .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c | |
247 | :internal: | |
248 | ||
3fe6c7f5 MR |
249 | GT Programming |
250 | ============== | |
251 | ||
252 | Multicast/Replicated (MCR) Registers | |
253 | ------------------------------------ | |
254 | ||
255 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c | |
256 | :doc: GT Multicast/Replicated (MCR) Register Support | |
257 | ||
258 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c | |
259 | :internal: | |
260 | ||
ca00c2b9 | 261 | Memory Management and Command Submission |
22554020 | 262 | ======================================== |
ca00c2b9 JN |
263 | |
264 | This sections covers all things related to the GEM implementation in the | |
265 | i915 driver. | |
266 | ||
fd5ff5f6 KR |
267 | Intel GPU Basics |
268 | ---------------- | |
269 | ||
270 | An Intel GPU has multiple engines. There are several engine types. | |
271 | ||
272 | - RCS engine is for rendering 3D and performing compute, this is named | |
273 | `I915_EXEC_RENDER` in user space. | |
274 | - BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user | |
275 | space. | |
276 | - VCS is a video encode and decode engine, this is named `I915_EXEC_BSD` | |
277 | in user space | |
278 | - VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user | |
279 | space. | |
280 | - The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine; | |
281 | instead it is to be used by user space to specify a default rendering | |
282 | engine (for 3D) that may or may not be the same as RCS. | |
283 | ||
284 | The Intel GPU family is a family of integrated GPU's using Unified | |
285 | Memory Access. For having the GPU "do work", user space will feed the | |
286 | GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2` | |
287 | or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will | |
288 | instruct the GPU to perform work (for example rendering) and that work | |
289 | needs memory from which to read and memory to which to write. All memory | |
290 | is encapsulated within GEM buffer objects (usually created with the ioctl | |
291 | `DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU | |
292 | to create will also list all GEM buffer objects that the batchbuffer reads | |
293 | and/or writes. For implementation details of memory management see | |
294 | `GEM BO Management Implementation Details`_. | |
295 | ||
296 | The i915 driver allows user space to create a context via the ioctl | |
297 | `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit | |
298 | integer. Such a context should be viewed by user-space as -loosely- | |
299 | analogous to the idea of a CPU process of an operating system. The i915 | |
300 | driver guarantees that commands issued to a fixed context are to be | |
301 | executed so that writes of a previously issued command are seen by | |
302 | reads of following commands. Actions issued between different contexts | |
303 | (even if from the same file descriptor) are NOT given that guarantee | |
304 | and the only way to synchronize across contexts (even from the same | |
305 | file descriptor) is through the use of fences. At least as far back as | |
306 | Gen4, also have that a context carries with it a GPU HW context; | |
307 | the HW context is essentially (most of atleast) the state of a GPU. | |
308 | In addition to the ordering guarantees, the kernel will restore GPU | |
309 | state via HW context when commands are issued to a context, this saves | |
310 | user space the need to restore (most of atleast) the GPU state at the | |
311 | start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer | |
312 | work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1) | |
313 | to identify what context to use with the command. | |
314 | ||
315 | The GPU has its own memory management and address space. The kernel | |
316 | driver maintains the memory translation table for the GPU. For older | |
317 | GPUs (i.e. those before Gen8), there is a single global such translation | |
318 | table, a global Graphics Translation Table (GTT). For newer generation | |
319 | GPUs each context has its own translation table, called Per-Process | |
320 | Graphics Translation Table (PPGTT). Of important note, is that although | |
321 | PPGTT is named per-process it is actually per context. When user space | |
322 | submits a batchbuffer, the kernel walks the list of GEM buffer objects | |
323 | used by the batchbuffer and guarantees that not only is the memory of | |
324 | each such GEM buffer object resident but it is also present in the | |
325 | (PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT, | |
326 | then it is given an address. Two consequences of this are: the kernel | |
327 | needs to edit the batchbuffer submitted to write the correct value of | |
328 | the GPU address when a GEM BO is assigned a GPU address and the kernel | |
329 | might evict a different GEM BO from the (PP)GTT to make address room | |
330 | for another GEM BO. Consequently, the ioctls submitting a batchbuffer | |
331 | for execution also include a list of all locations within buffers that | |
332 | refer to GPU-addresses so that the kernel can edit the buffer correctly. | |
333 | This process is dubbed relocation. | |
334 | ||
ca69a3c6 JL |
335 | Locking Guidelines |
336 | ------------------ | |
337 | ||
338 | .. note:: | |
339 | This is a description of how the locking should be after | |
340 | refactoring is done. Does not necessarily reflect what the locking | |
341 | looks like while WIP. | |
342 | ||
343 | #. All locking rules and interface contracts with cross-driver interfaces | |
344 | (dma-buf, dma_fence) need to be followed. | |
345 | ||
346 | #. No struct_mutex anywhere in the code | |
347 | ||
348 | #. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx | |
349 | is to be hoisted at highest level and passed down within i915_gem_ctx | |
350 | in the call chain | |
351 | ||
352 | #. While holding lru/memory manager (buddy, drm_mm, whatever) locks | |
353 | system memory allocations are not allowed | |
354 | ||
355 | * Enforce this by priming lockdep (with fs_reclaim). If we | |
356 | allocate memory while holding these looks we get a rehash | |
357 | of the shrinker vs. struct_mutex saga, and that would be | |
358 | real bad. | |
359 | ||
360 | #. Do not nest different lru/memory manager locks within each other. | |
361 | Take them in turn to update memory allocations, relying on the object’s | |
362 | dma_resv ww_mutex to serialize against other operations. | |
363 | ||
364 | #. The suggestion for lru/memory managers locks is that they are small | |
365 | enough to be spinlocks. | |
366 | ||
367 | #. All features need to come with exhaustive kernel selftests and/or | |
368 | IGT tests when appropriate | |
369 | ||
370 | #. All LMEM uAPI paths need to be fully restartable (_interruptible() | |
371 | for all locks/waits/sleeps) | |
372 | ||
373 | * Error handling validation through signal injection. | |
374 | Still the best strategy we have for validating GEM uAPI | |
375 | corner cases. | |
376 | Must be excessively used in the IGT, and we need to check | |
377 | that we really have full path coverage of all error cases. | |
378 | ||
379 | * -EDEADLK handling with ww_mutex | |
380 | ||
fd5ff5f6 KR |
381 | GEM BO Management Implementation Details |
382 | ---------------------------------------- | |
383 | ||
83dc7f69 | 384 | .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h |
fd5ff5f6 KR |
385 | :doc: Virtual Memory Address |
386 | ||
387 | Buffer Object Eviction | |
388 | ---------------------- | |
389 | ||
390 | This section documents the interface functions for evicting buffer | |
391 | objects to make space available in the virtual gpu address spaces. Note | |
392 | that this is mostly orthogonal to shrinking buffer objects caches, which | |
393 | has the goal to make main memory (shared with the gpu through the | |
394 | unified memory architecture) available. | |
395 | ||
396 | .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c | |
397 | :internal: | |
398 | ||
399 | Buffer Object Memory Shrinking | |
400 | ------------------------------ | |
401 | ||
402 | This section documents the interface function for shrinking memory usage | |
403 | of buffer object caches. Shrinking is used to make main memory | |
404 | available. Note that this is mostly orthogonal to evicting buffer | |
405 | objects, which has the goal to make space in gpu virtual address spaces. | |
406 | ||
8a6f43d4 | 407 | .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c |
fd5ff5f6 KR |
408 | :internal: |
409 | ||
ca00c2b9 | 410 | Batchbuffer Parsing |
22554020 | 411 | ------------------- |
ca00c2b9 JN |
412 | |
413 | .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c | |
414 | :doc: batch buffer command parser | |
415 | ||
416 | .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c | |
417 | :internal: | |
418 | ||
4d42db18 KR |
419 | User Batchbuffer Execution |
420 | -------------------------- | |
421 | ||
f8a9a5c2 JE |
422 | .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h |
423 | ||
8a6f43d4 | 424 | .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c |
4d42db18 KR |
425 | :doc: User command execution |
426 | ||
3e28d371 MB |
427 | Scheduling |
428 | ---------- | |
429 | .. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h | |
430 | :functions: i915_sched_engine | |
431 | ||
ca00c2b9 | 432 | Logical Rings, Logical Ring Contexts and Execlists |
22554020 | 433 | -------------------------------------------------- |
ca00c2b9 | 434 | |
3b7bc18b | 435 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_execlists_submission.c |
ca00c2b9 JN |
436 | :doc: Logical Rings, Logical Ring Contexts and Execlists |
437 | ||
ca00c2b9 | 438 | Global GTT views |
22554020 | 439 | ---------------- |
ca00c2b9 | 440 | |
83dc7f69 | 441 | .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h |
ca00c2b9 JN |
442 | :doc: Global GTT views |
443 | ||
444 | .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c | |
445 | :internal: | |
446 | ||
447 | GTT Fences and Swizzling | |
22554020 | 448 | ------------------------ |
ca00c2b9 | 449 | |
ba69fb16 | 450 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c |
ca00c2b9 JN |
451 | :internal: |
452 | ||
453 | Global GTT Fence Handling | |
22554020 | 454 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 | 455 | |
ba69fb16 | 456 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c |
ca00c2b9 JN |
457 | :doc: fence register handling |
458 | ||
459 | Hardware Tiling and Swizzling Details | |
22554020 | 460 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 | 461 | |
ba69fb16 | 462 | .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c |
ca00c2b9 JN |
463 | :doc: tiling swizzling details |
464 | ||
465 | Object Tiling IOCTLs | |
22554020 | 466 | -------------------- |
ca00c2b9 | 467 | |
8a6f43d4 | 468 | .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c |
ca00c2b9 JN |
469 | :internal: |
470 | ||
8a6f43d4 | 471 | .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c |
ca00c2b9 JN |
472 | :doc: buffer object tiling |
473 | ||
2d5517a5 DCS |
474 | Protected Objects |
475 | ----------------- | |
476 | ||
477 | .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp.c | |
478 | :doc: PXP | |
479 | ||
480 | .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h | |
481 | ||
493065e2 DCS |
482 | Microcontrollers |
483 | ================ | |
484 | ||
485 | Starting from gen9, three microcontrollers are available on the HW: the | |
486 | graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the | |
487 | display microcontroller (DMC). The driver is responsible for loading the | |
488 | firmwares on the microcontrollers; the GuC and HuC firmwares are transferred | |
489 | to WOPCM using the DMA engine, while the DMC firmware is written through MMIO. | |
490 | ||
fbe6f8f2 | 491 | WOPCM |
4072761b | 492 | ----- |
fbe6f8f2 YL |
493 | |
494 | WOPCM Layout | |
4072761b | 495 | ~~~~~~~~~~~~ |
fbe6f8f2 YL |
496 | |
497 | .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c | |
498 | :doc: WOPCM Layout | |
499 | ||
ca00c2b9 | 500 | GuC |
4072761b | 501 | --- |
ca00c2b9 | 502 | |
218151e9 DCS |
503 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c |
504 | :doc: GuC | |
505 | ||
4f41ddc7 MB |
506 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h |
507 | ||
218151e9 DCS |
508 | GuC Firmware Layout |
509 | ~~~~~~~~~~~~~~~~~~~ | |
199ddded | 510 | |
abf30f23 | 511 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h |
199ddded MW |
512 | :doc: Firmware Layout |
513 | ||
218151e9 DCS |
514 | GuC Memory Management |
515 | ~~~~~~~~~~~~~~~~~~~~~ | |
516 | ||
517 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c | |
518 | :doc: GuC Memory Management | |
519 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c | |
520 | :functions: intel_guc_allocate_vma | |
521 | ||
522 | ||
ca00c2b9 | 523 | GuC-specific firmware loader |
4072761b | 524 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 | 525 | |
dbbff8c3 | 526 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c |
ca00c2b9 JN |
527 | :internal: |
528 | ||
529 | GuC-based command submission | |
4072761b | 530 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
ca00c2b9 | 531 | |
dbbff8c3 | 532 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c |
ca00c2b9 JN |
533 | :doc: GuC-based command submission |
534 | ||
bfde26df MW |
535 | GuC ABI |
536 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
537 | ||
538 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_messages_abi.h | |
539 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h | |
540 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h | |
541 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_abi.h | |
77b6f79d | 542 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_klvs_abi.h |
bfde26df | 543 | |
493065e2 DCS |
544 | HuC |
545 | --- | |
0b23e2a6 DCS |
546 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c |
547 | :doc: HuC | |
548 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c | |
549 | :functions: intel_huc_auth | |
550 | ||
551 | HuC Memory Management | |
552 | ~~~~~~~~~~~~~~~~~~~~~ | |
553 | ||
554 | .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c | |
555 | :doc: HuC Memory Management | |
556 | ||
557 | HuC Firmware Layout | |
558 | ~~~~~~~~~~~~~~~~~~~ | |
559 | The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_ | |
493065e2 DCS |
560 | |
561 | DMC | |
562 | --- | |
32f9402d | 563 | See `DMC Firmware Support`_ |
493065e2 | 564 | |
ca00c2b9 | 565 | Tracing |
22554020 | 566 | ======= |
ca00c2b9 JN |
567 | |
568 | This sections covers all things related to the tracepoints implemented | |
569 | in the i915 driver. | |
570 | ||
571 | i915_ppgtt_create and i915_ppgtt_release | |
22554020 | 572 | ---------------------------------------- |
ca00c2b9 JN |
573 | |
574 | .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h | |
575 | :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints | |
576 | ||
577 | i915_context_create and i915_context_free | |
22554020 | 578 | ----------------------------------------- |
ca00c2b9 JN |
579 | |
580 | .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h | |
581 | :doc: i915_context_create and i915_context_free tracepoints | |
582 | ||
16d98b31 RB |
583 | Perf |
584 | ==== | |
585 | ||
586 | Overview | |
587 | -------- | |
588 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
589 | :doc: i915 Perf Overview | |
590 | ||
591 | Comparison with Core Perf | |
592 | ------------------------- | |
593 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
594 | :doc: i915 Perf History and Comparison with Core Perf | |
595 | ||
596 | i915 Driver Entry Points | |
597 | ------------------------ | |
598 | ||
599 | This section covers the entrypoints exported outside of i915_perf.c to | |
600 | integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl. | |
601 | ||
602 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
603 | :functions: i915_perf_init | |
604 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
605 | :functions: i915_perf_fini | |
606 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
607 | :functions: i915_perf_register | |
608 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
609 | :functions: i915_perf_unregister | |
610 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
611 | :functions: i915_perf_open_ioctl | |
612 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
613 | :functions: i915_perf_release | |
f89823c2 LL |
614 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c |
615 | :functions: i915_perf_add_config_ioctl | |
616 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
617 | :functions: i915_perf_remove_config_ioctl | |
16d98b31 RB |
618 | |
619 | i915 Perf Stream | |
620 | ---------------- | |
621 | ||
622 | This section covers the stream-semantics-agnostic structures and functions | |
623 | for representing an i915 perf stream FD and associated file operations. | |
624 | ||
8c638802 | 625 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h |
16d98b31 | 626 | :functions: i915_perf_stream |
8c638802 | 627 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h |
16d98b31 RB |
628 | :functions: i915_perf_stream_ops |
629 | ||
630 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
631 | :functions: read_properties_unlocked | |
632 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
633 | :functions: i915_perf_open_ioctl_locked | |
634 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
635 | :functions: i915_perf_destroy_locked | |
636 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
637 | :functions: i915_perf_read | |
638 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
639 | :functions: i915_perf_ioctl | |
640 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
641 | :functions: i915_perf_enable_locked | |
642 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
643 | :functions: i915_perf_disable_locked | |
644 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
645 | :functions: i915_perf_poll | |
646 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
647 | :functions: i915_perf_poll_locked | |
648 | ||
649 | i915 Perf Observation Architecture Stream | |
650 | ----------------------------------------- | |
651 | ||
8c638802 | 652 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h |
16d98b31 RB |
653 | :functions: i915_oa_ops |
654 | ||
655 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
656 | :functions: i915_oa_stream_init | |
657 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
658 | :functions: i915_oa_read | |
659 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
660 | :functions: i915_oa_stream_enable | |
661 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
662 | :functions: i915_oa_stream_disable | |
663 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
664 | :functions: i915_oa_wait_unlocked | |
665 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
666 | :functions: i915_oa_poll_wait | |
667 | ||
11604da2 MCC |
668 | Other i915 Perf Internals |
669 | ------------------------- | |
16d98b31 | 670 | |
11604da2 MCC |
671 | This section simply includes all other currently documented i915 perf internals, |
672 | in no particular order, but may include some more minor utilities or platform | |
16d98b31 RB |
673 | specific details than found in the more high-level sections. |
674 | ||
675 | .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
676 | :internal: | |
11604da2 MCC |
677 | :no-identifiers: |
678 | i915_perf_init | |
679 | i915_perf_fini | |
680 | i915_perf_register | |
681 | i915_perf_unregister | |
682 | i915_perf_open_ioctl | |
683 | i915_perf_release | |
684 | i915_perf_add_config_ioctl | |
685 | i915_perf_remove_config_ioctl | |
686 | read_properties_unlocked | |
687 | i915_perf_open_ioctl_locked | |
688 | i915_perf_destroy_locked | |
689 | i915_perf_read i915_perf_ioctl | |
690 | i915_perf_enable_locked | |
691 | i915_perf_disable_locked | |
692 | i915_perf_poll i915_perf_poll_locked | |
693 | i915_oa_stream_init i915_oa_read | |
694 | i915_oa_stream_enable | |
695 | i915_oa_stream_disable | |
696 | i915_oa_wait_unlocked | |
697 | i915_oa_poll_wait | |
1aa920ea JN |
698 | |
699 | Style | |
700 | ===== | |
701 | ||
702 | The drm/i915 driver codebase has some style rules in addition to (and, in some | |
703 | cases, deviating from) the kernel coding style. | |
704 | ||
705 | Register macro definition style | |
706 | ------------------------------- | |
707 | ||
708 | The style guide for ``i915_reg.h``. | |
709 | ||
710 | .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h | |
711 | :doc: The i915 register macro definition style guide | |
055634e4 TU |
712 | |
713 | .. _i915-usage-stats: | |
714 | ||
715 | i915 DRM client usage stats implementation | |
716 | ========================================== | |
717 | ||
718 | The drm/i915 driver implements the DRM client usage stats specification as | |
719 | documented in :ref:`drm-client-usage-stats`. | |
720 | ||
721 | Example of the output showing the implemented key value pairs and entirety of | |
722 | the currently possible format options: | |
723 | ||
724 | :: | |
725 | ||
726 | pos: 0 | |
727 | flags: 0100002 | |
728 | mnt_id: 21 | |
729 | drm-driver: i915 | |
730 | drm-pdev: 0000:00:02.0 | |
731 | drm-client-id: 7 | |
732 | drm-engine-render: 9288864723 ns | |
733 | drm-engine-copy: 2035071108 ns | |
734 | drm-engine-video: 0 ns | |
735 | drm-engine-capacity-video: 2 | |
736 | drm-engine-video-enhance: 0 ns | |
737 | ||
738 | Possible `drm-engine-` key names are: `render`, `copy`, `video` and | |
739 | `video-enhance`. |