1 ===========================
2 drm/i915 Intel GFX Driver
3 ===========================
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.
10 Core Driver Infrastructure
11 ==========================
13 This section covers core driver infrastructure used by both the display
14 and the GEM parts of the driver.
16 Runtime Power Management
17 ------------------------
19 .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c
22 .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c
25 .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c
31 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
32 :doc: interrupt handling
34 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
35 :functions: intel_irq_init intel_irq_init_hw intel_hpd_init
37 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
38 :functions: intel_runtime_pm_disable_interrupts
40 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
41 :functions: intel_runtime_pm_enable_interrupts
43 Intel GVT-g Guest Support(vGPU)
44 -------------------------------
46 .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
47 :doc: Intel GVT-g guest support
49 .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
52 Intel GVT-g Host Support(vGPU device model)
53 -------------------------------------------
55 .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
56 :doc: Intel GVT-g host support
58 .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
64 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
65 :doc: Hardware workarounds
67 Display Hardware Handling
68 =========================
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.
74 Mode Setting Infrastructure
75 ---------------------------
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
85 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
86 :doc: frontbuffer tracking
88 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h
91 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
94 Display FIFO Underrun Reporting
95 -------------------------------
97 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
98 :doc: fifo underrun handling
100 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
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
115 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
116 :doc: atomic plane helpers
118 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
121 Asynchronous Page Flip
122 ----------------------
124 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
125 :doc: asynchronous flip implementation
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.
138 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
141 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
144 High Definition Audio
145 ---------------------
147 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
148 :doc: High Definition Audio over HDMI and Display Port
150 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
153 .. kernel-doc:: include/drm/i915_component.h
156 Intel HDMI LPE Audio Support
157 ----------------------------
159 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
160 :doc: LPE Audio integration for HDMI or DP playback
162 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
165 Panel Self Refresh PSR (PSR/SRD)
166 --------------------------------
168 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
169 :doc: Panel Self Refresh (PSR/SRD)
171 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
174 Frame Buffer Compression (FBC)
175 ------------------------------
177 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
178 :doc: Frame Buffer Compression (FBC)
180 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
183 Display Refresh Rate Switching (DRRS)
184 -------------------------------------
186 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
187 :doc: Display Refresh Rate Switching (DRRS)
189 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
195 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
201 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
202 :doc: DMC Firmware Support
204 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
207 Video BIOS Table (VBT)
208 ----------------------
210 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
211 :doc: Video BIOS Table (VBT)
213 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
216 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h
222 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
225 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
231 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
234 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
237 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
243 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
246 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
249 Memory Management and Command Submission
250 ========================================
252 This sections covers all things related to the GEM implementation in the
258 An Intel GPU has multiple engines. There are several engine types.
260 - RCS engine is for rendering 3D and performing compute, this is named
261 `I915_EXEC_RENDER` in user space.
262 - BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user
264 - VCS is a video encode and decode engine, this is named `I915_EXEC_BSD`
266 - VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user
268 - The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine;
269 instead it is to be used by user space to specify a default rendering
270 engine (for 3D) that may or may not be the same as RCS.
272 The Intel GPU family is a family of integrated GPU's using Unified
273 Memory Access. For having the GPU "do work", user space will feed the
274 GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
275 or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
276 instruct the GPU to perform work (for example rendering) and that work
277 needs memory from which to read and memory to which to write. All memory
278 is encapsulated within GEM buffer objects (usually created with the ioctl
279 `DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
280 to create will also list all GEM buffer objects that the batchbuffer reads
281 and/or writes. For implementation details of memory management see
282 `GEM BO Management Implementation Details`_.
284 The i915 driver allows user space to create a context via the ioctl
285 `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit
286 integer. Such a context should be viewed by user-space as -loosely-
287 analogous to the idea of a CPU process of an operating system. The i915
288 driver guarantees that commands issued to a fixed context are to be
289 executed so that writes of a previously issued command are seen by
290 reads of following commands. Actions issued between different contexts
291 (even if from the same file descriptor) are NOT given that guarantee
292 and the only way to synchronize across contexts (even from the same
293 file descriptor) is through the use of fences. At least as far back as
294 Gen4, also have that a context carries with it a GPU HW context;
295 the HW context is essentially (most of atleast) the state of a GPU.
296 In addition to the ordering guarantees, the kernel will restore GPU
297 state via HW context when commands are issued to a context, this saves
298 user space the need to restore (most of atleast) the GPU state at the
299 start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
300 work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
301 to identify what context to use with the command.
303 The GPU has its own memory management and address space. The kernel
304 driver maintains the memory translation table for the GPU. For older
305 GPUs (i.e. those before Gen8), there is a single global such translation
306 table, a global Graphics Translation Table (GTT). For newer generation
307 GPUs each context has its own translation table, called Per-Process
308 Graphics Translation Table (PPGTT). Of important note, is that although
309 PPGTT is named per-process it is actually per context. When user space
310 submits a batchbuffer, the kernel walks the list of GEM buffer objects
311 used by the batchbuffer and guarantees that not only is the memory of
312 each such GEM buffer object resident but it is also present in the
313 (PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT,
314 then it is given an address. Two consequences of this are: the kernel
315 needs to edit the batchbuffer submitted to write the correct value of
316 the GPU address when a GEM BO is assigned a GPU address and the kernel
317 might evict a different GEM BO from the (PP)GTT to make address room
318 for another GEM BO. Consequently, the ioctls submitting a batchbuffer
319 for execution also include a list of all locations within buffers that
320 refer to GPU-addresses so that the kernel can edit the buffer correctly.
321 This process is dubbed relocation.
327 This is a description of how the locking should be after
328 refactoring is done. Does not necessarily reflect what the locking
329 looks like while WIP.
331 #. All locking rules and interface contracts with cross-driver interfaces
332 (dma-buf, dma_fence) need to be followed.
334 #. No struct_mutex anywhere in the code
336 #. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx
337 is to be hoisted at highest level and passed down within i915_gem_ctx
340 #. While holding lru/memory manager (buddy, drm_mm, whatever) locks
341 system memory allocations are not allowed
343 * Enforce this by priming lockdep (with fs_reclaim). If we
344 allocate memory while holding these looks we get a rehash
345 of the shrinker vs. struct_mutex saga, and that would be
348 #. Do not nest different lru/memory manager locks within each other.
349 Take them in turn to update memory allocations, relying on the object’s
350 dma_resv ww_mutex to serialize against other operations.
352 #. The suggestion for lru/memory managers locks is that they are small
353 enough to be spinlocks.
355 #. All features need to come with exhaustive kernel selftests and/or
356 IGT tests when appropriate
358 #. All LMEM uAPI paths need to be fully restartable (_interruptible()
359 for all locks/waits/sleeps)
361 * Error handling validation through signal injection.
362 Still the best strategy we have for validating GEM uAPI
364 Must be excessively used in the IGT, and we need to check
365 that we really have full path coverage of all error cases.
367 * -EDEADLK handling with ww_mutex
369 GEM BO Management Implementation Details
370 ----------------------------------------
372 .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h
373 :doc: Virtual Memory Address
375 Buffer Object Eviction
376 ----------------------
378 This section documents the interface functions for evicting buffer
379 objects to make space available in the virtual gpu address spaces. Note
380 that this is mostly orthogonal to shrinking buffer objects caches, which
381 has the goal to make main memory (shared with the gpu through the
382 unified memory architecture) available.
384 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c
387 Buffer Object Memory Shrinking
388 ------------------------------
390 This section documents the interface function for shrinking memory usage
391 of buffer object caches. Shrinking is used to make main memory
392 available. Note that this is mostly orthogonal to evicting buffer
393 objects, which has the goal to make space in gpu virtual address spaces.
395 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
401 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
402 :doc: batch buffer command parser
404 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
407 User Batchbuffer Execution
408 --------------------------
410 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h
412 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
413 :doc: User command execution
417 .. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h
418 :functions: i915_sched_engine
420 Logical Rings, Logical Ring Contexts and Execlists
421 --------------------------------------------------
423 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_execlists_submission.c
424 :doc: Logical Rings, Logical Ring Contexts and Execlists
429 .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h
430 :doc: Global GTT views
432 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
435 GTT Fences and Swizzling
436 ------------------------
438 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
441 Global GTT Fence Handling
442 ~~~~~~~~~~~~~~~~~~~~~~~~~
444 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
445 :doc: fence register handling
447 Hardware Tiling and Swizzling Details
448 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
450 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
451 :doc: tiling swizzling details
456 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
459 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
460 :doc: buffer object tiling
465 .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp.c
468 .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h
473 Starting from gen9, three microcontrollers are available on the HW: the
474 graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the
475 display microcontroller (DMC). The driver is responsible for loading the
476 firmwares on the microcontrollers; the GuC and HuC firmwares are transferred
477 to WOPCM using the DMA engine, while the DMC firmware is written through MMIO.
485 .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c
491 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
494 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
499 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h
500 :doc: Firmware Layout
502 GuC Memory Management
503 ~~~~~~~~~~~~~~~~~~~~~
505 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
506 :doc: GuC Memory Management
507 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
508 :functions: intel_guc_allocate_vma
511 GuC-specific firmware loader
512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
514 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
517 GuC-based command submission
518 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
520 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
521 :doc: GuC-based command submission
524 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
526 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_messages_abi.h
527 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h
528 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h
529 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_abi.h
530 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_klvs_abi.h
534 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
536 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
537 :functions: intel_huc_auth
539 HuC Memory Management
540 ~~~~~~~~~~~~~~~~~~~~~
542 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
543 :doc: HuC Memory Management
547 The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_
551 See `DMC Firmware Support`_
556 This sections covers all things related to the tracepoints implemented
559 i915_ppgtt_create and i915_ppgtt_release
560 ----------------------------------------
562 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
563 :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints
565 i915_context_create and i915_context_free
566 -----------------------------------------
568 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
569 :doc: i915_context_create and i915_context_free tracepoints
576 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
577 :doc: i915 Perf Overview
579 Comparison with Core Perf
580 -------------------------
581 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
582 :doc: i915 Perf History and Comparison with Core Perf
584 i915 Driver Entry Points
585 ------------------------
587 This section covers the entrypoints exported outside of i915_perf.c to
588 integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl.
590 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
591 :functions: i915_perf_init
592 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
593 :functions: i915_perf_fini
594 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
595 :functions: i915_perf_register
596 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
597 :functions: i915_perf_unregister
598 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
599 :functions: i915_perf_open_ioctl
600 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
601 :functions: i915_perf_release
602 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
603 :functions: i915_perf_add_config_ioctl
604 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
605 :functions: i915_perf_remove_config_ioctl
610 This section covers the stream-semantics-agnostic structures and functions
611 for representing an i915 perf stream FD and associated file operations.
613 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
614 :functions: i915_perf_stream
615 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
616 :functions: i915_perf_stream_ops
618 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
619 :functions: read_properties_unlocked
620 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
621 :functions: i915_perf_open_ioctl_locked
622 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
623 :functions: i915_perf_destroy_locked
624 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
625 :functions: i915_perf_read
626 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
627 :functions: i915_perf_ioctl
628 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
629 :functions: i915_perf_enable_locked
630 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
631 :functions: i915_perf_disable_locked
632 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
633 :functions: i915_perf_poll
634 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
635 :functions: i915_perf_poll_locked
637 i915 Perf Observation Architecture Stream
638 -----------------------------------------
640 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
641 :functions: i915_oa_ops
643 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
644 :functions: i915_oa_stream_init
645 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
646 :functions: i915_oa_read
647 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
648 :functions: i915_oa_stream_enable
649 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
650 :functions: i915_oa_stream_disable
651 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
652 :functions: i915_oa_wait_unlocked
653 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
654 :functions: i915_oa_poll_wait
656 Other i915 Perf Internals
657 -------------------------
659 This section simply includes all other currently documented i915 perf internals,
660 in no particular order, but may include some more minor utilities or platform
661 specific details than found in the more high-level sections.
663 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
672 i915_perf_add_config_ioctl
673 i915_perf_remove_config_ioctl
674 read_properties_unlocked
675 i915_perf_open_ioctl_locked
676 i915_perf_destroy_locked
677 i915_perf_read i915_perf_ioctl
678 i915_perf_enable_locked
679 i915_perf_disable_locked
680 i915_perf_poll i915_perf_poll_locked
681 i915_oa_stream_init i915_oa_read
682 i915_oa_stream_enable
683 i915_oa_stream_disable
684 i915_oa_wait_unlocked
690 The drm/i915 driver codebase has some style rules in addition to (and, in some
691 cases, deviating from) the kernel coding style.
693 Register macro definition style
694 -------------------------------
696 The style guide for ``i915_reg.h``.
698 .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
699 :doc: The i915 register macro definition style guide
701 .. _i915-usage-stats:
703 i915 DRM client usage stats implementation
704 ==========================================
706 The drm/i915 driver implements the DRM client usage stats specification as
707 documented in :ref:`drm-client-usage-stats`.
709 Example of the output showing the implemented key value pairs and entirety of
710 the currently possible format options:
718 drm-pdev: 0000:00:02.0
720 drm-engine-render: 9288864723 ns
721 drm-engine-copy: 2035071108 ns
722 drm-engine-video: 0 ns
723 drm-engine-capacity-video: 2
724 drm-engine-video-enhance: 0 ns
726 Possible `drm-engine-` key names are: `render`, `copy`, `video` and