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
124 This section covers output probing and related infrastructure like the
125 hotplug interrupt storm detection and mitigation code. Note that the
126 i915 driver still uses most of the common DRM helper code for output
127 probing, so those sections fully apply.
132 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
135 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
138 High Definition Audio
139 ---------------------
141 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
142 :doc: High Definition Audio over HDMI and Display Port
144 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
147 .. kernel-doc:: include/drm/i915_component.h
150 Intel HDMI LPE Audio Support
151 ----------------------------
153 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
154 :doc: LPE Audio integration for HDMI or DP playback
156 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
159 Panel Self Refresh PSR (PSR/SRD)
160 --------------------------------
162 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
163 :doc: Panel Self Refresh (PSR/SRD)
165 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
168 Frame Buffer Compression (FBC)
169 ------------------------------
171 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
172 :doc: Frame Buffer Compression (FBC)
174 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
177 Display Refresh Rate Switching (DRRS)
178 -------------------------------------
180 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
181 :doc: Display Refresh Rate Switching (DRRS)
183 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
184 :functions: intel_dp_set_drrs_state
186 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
187 :functions: intel_edp_drrs_enable
189 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
190 :functions: intel_edp_drrs_disable
192 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
193 :functions: intel_edp_drrs_invalidate
195 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
196 :functions: intel_edp_drrs_flush
198 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
199 :functions: intel_dp_drrs_init
204 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
207 CSR firmware support for DMC
208 ----------------------------
210 .. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
211 :doc: csr support for dmc
213 .. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
216 Video BIOS Table (VBT)
217 ----------------------
219 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
220 :doc: Video BIOS Table (VBT)
222 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
225 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h
231 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
234 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
240 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
243 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
246 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
252 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
255 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
258 Memory Management and Command Submission
259 ========================================
261 This sections covers all things related to the GEM implementation in the
267 An Intel GPU has multiple engines. There are several engine types.
269 - RCS engine is for rendering 3D and performing compute, this is named
270 `I915_EXEC_RENDER` in user space.
271 - BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user
273 - VCS is a video encode and decode engine, this is named `I915_EXEC_BSD`
275 - VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user
277 - The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine;
278 instead it is to be used by user space to specify a default rendering
279 engine (for 3D) that may or may not be the same as RCS.
281 The Intel GPU family is a family of integrated GPU's using Unified
282 Memory Access. For having the GPU "do work", user space will feed the
283 GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
284 or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
285 instruct the GPU to perform work (for example rendering) and that work
286 needs memory from which to read and memory to which to write. All memory
287 is encapsulated within GEM buffer objects (usually created with the ioctl
288 `DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
289 to create will also list all GEM buffer objects that the batchbuffer reads
290 and/or writes. For implementation details of memory management see
291 `GEM BO Management Implementation Details`_.
293 The i915 driver allows user space to create a context via the ioctl
294 `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit
295 integer. Such a context should be viewed by user-space as -loosely-
296 analogous to the idea of a CPU process of an operating system. The i915
297 driver guarantees that commands issued to a fixed context are to be
298 executed so that writes of a previously issued command are seen by
299 reads of following commands. Actions issued between different contexts
300 (even if from the same file descriptor) are NOT given that guarantee
301 and the only way to synchronize across contexts (even from the same
302 file descriptor) is through the use of fences. At least as far back as
303 Gen4, also have that a context carries with it a GPU HW context;
304 the HW context is essentially (most of atleast) the state of a GPU.
305 In addition to the ordering guarantees, the kernel will restore GPU
306 state via HW context when commands are issued to a context, this saves
307 user space the need to restore (most of atleast) the GPU state at the
308 start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
309 work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
310 to identify what context to use with the command.
312 The GPU has its own memory management and address space. The kernel
313 driver maintains the memory translation table for the GPU. For older
314 GPUs (i.e. those before Gen8), there is a single global such translation
315 table, a global Graphics Translation Table (GTT). For newer generation
316 GPUs each context has its own translation table, called Per-Process
317 Graphics Translation Table (PPGTT). Of important note, is that although
318 PPGTT is named per-process it is actually per context. When user space
319 submits a batchbuffer, the kernel walks the list of GEM buffer objects
320 used by the batchbuffer and guarantees that not only is the memory of
321 each such GEM buffer object resident but it is also present in the
322 (PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT,
323 then it is given an address. Two consequences of this are: the kernel
324 needs to edit the batchbuffer submitted to write the correct value of
325 the GPU address when a GEM BO is assigned a GPU address and the kernel
326 might evict a different GEM BO from the (PP)GTT to make address room
327 for another GEM BO. Consequently, the ioctls submitting a batchbuffer
328 for execution also include a list of all locations within buffers that
329 refer to GPU-addresses so that the kernel can edit the buffer correctly.
330 This process is dubbed relocation.
332 GEM BO Management Implementation Details
333 ----------------------------------------
335 .. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
336 :doc: Virtual Memory Address
338 Buffer Object Eviction
339 ----------------------
341 This section documents the interface functions for evicting buffer
342 objects to make space available in the virtual gpu address spaces. Note
343 that this is mostly orthogonal to shrinking buffer objects caches, which
344 has the goal to make main memory (shared with the gpu through the
345 unified memory architecture) available.
347 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c
350 Buffer Object Memory Shrinking
351 ------------------------------
353 This section documents the interface function for shrinking memory usage
354 of buffer object caches. Shrinking is used to make main memory
355 available. Note that this is mostly orthogonal to evicting buffer
356 objects, which has the goal to make space in gpu virtual address spaces.
358 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
364 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
365 :doc: batch buffer command parser
367 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
370 User Batchbuffer Execution
371 --------------------------
373 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
374 :doc: User command execution
376 Logical Rings, Logical Ring Contexts and Execlists
377 --------------------------------------------------
379 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c
380 :doc: Logical Rings, Logical Ring Contexts and Execlists
385 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
386 :doc: Global GTT views
388 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
391 GTT Fences and Swizzling
392 ------------------------
394 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
397 Global GTT Fence Handling
398 ~~~~~~~~~~~~~~~~~~~~~~~~~
400 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
401 :doc: fence register handling
403 Hardware Tiling and Swizzling Details
404 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
406 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
407 :doc: tiling swizzling details
412 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
415 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
416 :doc: buffer object tiling
421 Starting from gen9, three microcontrollers are available on the HW: the
422 graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the
423 display microcontroller (DMC). The driver is responsible for loading the
424 firmwares on the microcontrollers; the GuC and HuC firmwares are transferred
425 to WOPCM using the DMA engine, while the DMC firmware is written through MMIO.
433 .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c
439 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
445 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h
446 :doc: Firmware Layout
448 GuC Memory Management
449 ~~~~~~~~~~~~~~~~~~~~~
451 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
452 :doc: GuC Memory Management
453 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
454 :functions: intel_guc_allocate_vma
457 GuC-specific firmware loader
458 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
460 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
463 GuC-based command submission
464 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
466 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
467 :doc: GuC-based command submission
469 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
474 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
476 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
477 :functions: intel_huc_auth
479 HuC Memory Management
480 ~~~~~~~~~~~~~~~~~~~~~
482 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
483 :doc: HuC Memory Management
487 The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_
491 See `CSR firmware support for DMC`_
496 This sections covers all things related to the tracepoints implemented
499 i915_ppgtt_create and i915_ppgtt_release
500 ----------------------------------------
502 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
503 :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints
505 i915_context_create and i915_context_free
506 -----------------------------------------
508 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
509 :doc: i915_context_create and i915_context_free tracepoints
516 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
517 :doc: i915 Perf Overview
519 Comparison with Core Perf
520 -------------------------
521 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
522 :doc: i915 Perf History and Comparison with Core Perf
524 i915 Driver Entry Points
525 ------------------------
527 This section covers the entrypoints exported outside of i915_perf.c to
528 integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl.
530 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
531 :functions: i915_perf_init
532 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
533 :functions: i915_perf_fini
534 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
535 :functions: i915_perf_register
536 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
537 :functions: i915_perf_unregister
538 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
539 :functions: i915_perf_open_ioctl
540 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
541 :functions: i915_perf_release
542 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
543 :functions: i915_perf_add_config_ioctl
544 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
545 :functions: i915_perf_remove_config_ioctl
550 This section covers the stream-semantics-agnostic structures and functions
551 for representing an i915 perf stream FD and associated file operations.
553 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
554 :functions: i915_perf_stream
555 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
556 :functions: i915_perf_stream_ops
558 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
559 :functions: read_properties_unlocked
560 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
561 :functions: i915_perf_open_ioctl_locked
562 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
563 :functions: i915_perf_destroy_locked
564 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
565 :functions: i915_perf_read
566 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
567 :functions: i915_perf_ioctl
568 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
569 :functions: i915_perf_enable_locked
570 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
571 :functions: i915_perf_disable_locked
572 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
573 :functions: i915_perf_poll
574 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
575 :functions: i915_perf_poll_locked
577 i915 Perf Observation Architecture Stream
578 -----------------------------------------
580 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
581 :functions: i915_oa_ops
583 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
584 :functions: i915_oa_stream_init
585 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
586 :functions: i915_oa_read
587 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
588 :functions: i915_oa_stream_enable
589 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
590 :functions: i915_oa_stream_disable
591 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
592 :functions: i915_oa_wait_unlocked
593 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
594 :functions: i915_oa_poll_wait
596 All i915 Perf Internals
597 -----------------------
599 This section simply includes all currently documented i915 perf internals, in
600 no particular order, but may include some more minor utilities or platform
601 specific details than found in the more high-level sections.
603 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
609 The drm/i915 driver codebase has some style rules in addition to (and, in some
610 cases, deviating from) the kernel coding style.
612 Register macro definition style
613 -------------------------------
615 The style guide for ``i915_reg.h``.
617 .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
618 :doc: The i915 register macro definition style guide