1===========================
2 drm/i915 Intel GFX Driver
3===========================
4
5The drm/i915 driver supports all (with the exception of some very early
6models) integrated GFX chipsets with both Intel display and rendering
7blocks. This excludes a set of SoC platforms with an SGX rendering unit,
8those have basic support through the gma500 drm driver.
9
10Core Driver Infrastructure
11==========================
12
13This section covers core driver infrastructure used by both the display
14and the GEM parts of the driver.
15
16Runtime Power Management
17------------------------
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
28Interrupt Handling
29------------------
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
43Intel GVT-g Guest Support(vGPU)
44-------------------------------
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
52Intel 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
61Workarounds
62-----------
63
64.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
65   :doc: Hardware workarounds
66
67Display Hardware Handling
68=========================
69
70This section covers everything related to the display hardware including
71the mode setting infrastructure, plane, sprite and cursor handling and
72display, output probing and related topics.
73
74Mode Setting Infrastructure
75---------------------------
76
77The i915 driver is thus far the only DRM driver which doesn't use the
78common DRM helper code to implement mode setting sequences. Thus it has
79its own tailor-made infrastructure for executing a display configuration
80change.
81
82Frontbuffer Tracking
83--------------------
84
85.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
86   :doc: frontbuffer tracking
87
88.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h
89   :internal:
90
91.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
92   :internal:
93
94Display FIFO Underrun Reporting
95-------------------------------
96
97.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
98   :doc: fifo underrun handling
99
100.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
101   :internal:
102
103Plane Configuration
104-------------------
105
106This section covers plane configuration and composition with the primary
107plane, sprites, cursors and overlays. This includes the infrastructure
108to do atomic vsync'ed updates of all this state and also tightly coupled
109topics like watermark setup and computation, framebuffer compression and
110panel self refresh.
111
112Atomic Plane Helpers
113--------------------
114
115.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
116   :doc: atomic plane helpers
117
118.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
119   :internal:
120
121Output Probing
122--------------
123
124This section covers output probing and related infrastructure like the
125hotplug interrupt storm detection and mitigation code. Note that the
126i915 driver still uses most of the common DRM helper code for output
127probing, so those sections fully apply.
128
129Hotplug
130-------
131
132.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
133   :doc: Hotplug
134
135.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
136   :internal:
137
138High Definition Audio
139---------------------
140
141.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
142   :doc: High Definition Audio over HDMI and Display Port
143
144.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
145   :internal:
146
147.. kernel-doc:: include/drm/i915_component.h
148   :internal:
149
150Intel HDMI LPE Audio Support
151----------------------------
152
153.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
154   :doc: LPE Audio integration for HDMI or DP playback
155
156.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
157   :internal:
158
159Panel Self Refresh PSR (PSR/SRD)
160--------------------------------
161
162.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
163   :doc: Panel Self Refresh (PSR/SRD)
164
165.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
166   :internal:
167
168Frame Buffer Compression (FBC)
169------------------------------
170
171.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
172   :doc: Frame Buffer Compression (FBC)
173
174.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
175   :internal:
176
177Display Refresh Rate Switching (DRRS)
178-------------------------------------
179
180.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
181   :doc: Display Refresh Rate Switching (DRRS)
182
183.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
184   :functions: intel_dp_set_drrs_state
185
186.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
187   :functions: intel_edp_drrs_enable
188
189.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
190   :functions: intel_edp_drrs_disable
191
192.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
193   :functions: intel_edp_drrs_invalidate
194
195.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
196   :functions: intel_edp_drrs_flush
197
198.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
199   :functions: intel_dp_drrs_init
200
201DPIO
202----
203
204.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
205   :doc: DPIO
206
207CSR firmware support for DMC
208----------------------------
209
210.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
211   :doc: csr support for dmc
212
213.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
214   :internal:
215
216Video BIOS Table (VBT)
217----------------------
218
219.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
220   :doc: Video BIOS Table (VBT)
221
222.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
223   :internal:
224
225.. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h
226   :internal:
227
228Display clocks
229--------------
230
231.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
232   :doc: CDCLK / RAWCLK
233
234.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
235   :internal:
236
237Display PLLs
238------------
239
240.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
241   :doc: Display PLLs
242
243.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
244   :internal:
245
246.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
247   :internal:
248
249Memory Management and Command Submission
250========================================
251
252This sections covers all things related to the GEM implementation in the
253i915 driver.
254
255Intel GPU Basics
256----------------
257
258An Intel GPU has multiple engines. There are several engine types.
259
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
263  space.
264- VCS is a video encode and decode engine, this is named `I915_EXEC_BSD`
265  in user space
266- VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user
267  space.
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.
271
272The Intel GPU family is a family of integrated GPU's using Unified
273Memory Access. For having the GPU "do work", user space will feed the
274GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
275or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
276instruct the GPU to perform work (for example rendering) and that work
277needs memory from which to read and memory to which to write. All memory
278is encapsulated within GEM buffer objects (usually created with the ioctl
279`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
280to create will also list all GEM buffer objects that the batchbuffer reads
281and/or writes. For implementation details of memory management see
282`GEM BO Management Implementation Details`_.
283
284The 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
286integer. Such a context should be viewed by user-space as -loosely-
287analogous to the idea of a CPU process of an operating system. The i915
288driver guarantees that commands issued to a fixed context are to be
289executed so that writes of a previously issued command are seen by
290reads of following commands. Actions issued between different contexts
291(even if from the same file descriptor) are NOT given that guarantee
292and the only way to synchronize across contexts (even from the same
293file descriptor) is through the use of fences. At least as far back as
294Gen4, also have that a context carries with it a GPU HW context;
295the HW context is essentially (most of atleast) the state of a GPU.
296In addition to the ordering guarantees, the kernel will restore GPU
297state via HW context when commands are issued to a context, this saves
298user space the need to restore (most of atleast) the GPU state at the
299start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
300work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
301to identify what context to use with the command.
302
303The GPU has its own memory management and address space. The kernel
304driver maintains the memory translation table for the GPU. For older
305GPUs (i.e. those before Gen8), there is a single global such translation
306table, a global Graphics Translation Table (GTT). For newer generation
307GPUs each context has its own translation table, called Per-Process
308Graphics Translation Table (PPGTT). Of important note, is that although
309PPGTT is named per-process it is actually per context. When user space
310submits a batchbuffer, the kernel walks the list of GEM buffer objects
311used by the batchbuffer and guarantees that not only is the memory of
312each 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,
314then it is given an address. Two consequences of this are: the kernel
315needs to edit the batchbuffer submitted to write the correct value of
316the GPU address when a GEM BO is assigned a GPU address and the kernel
317might evict a different GEM BO from the (PP)GTT to make address room
318for another GEM BO. Consequently, the ioctls submitting a batchbuffer
319for execution also include a list of all locations within buffers that
320refer to GPU-addresses so that the kernel can edit the buffer correctly.
321This process is dubbed relocation.
322
323GEM BO Management Implementation Details
324----------------------------------------
325
326.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
327   :doc: Virtual Memory Address
328
329Buffer Object Eviction
330----------------------
331
332This section documents the interface functions for evicting buffer
333objects to make space available in the virtual gpu address spaces. Note
334that this is mostly orthogonal to shrinking buffer objects caches, which
335has the goal to make main memory (shared with the gpu through the
336unified memory architecture) available.
337
338.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c
339   :internal:
340
341Buffer Object Memory Shrinking
342------------------------------
343
344This section documents the interface function for shrinking memory usage
345of buffer object caches. Shrinking is used to make main memory
346available. Note that this is mostly orthogonal to evicting buffer
347objects, which has the goal to make space in gpu virtual address spaces.
348
349.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
350   :internal:
351
352Batchbuffer Parsing
353-------------------
354
355.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
356   :doc: batch buffer command parser
357
358.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
359   :internal:
360
361Batchbuffer Pools
362-----------------
363
364.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
365   :doc: batch pool
366
367.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
368   :internal:
369
370User Batchbuffer Execution
371--------------------------
372
373.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
374   :doc: User command execution
375
376Logical Rings, Logical Ring Contexts and Execlists
377--------------------------------------------------
378
379.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c
380   :doc: Logical Rings, Logical Ring Contexts and Execlists
381
382Global GTT views
383----------------
384
385.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
386   :doc: Global GTT views
387
388.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
389   :internal:
390
391GTT Fences and Swizzling
392------------------------
393
394.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
395   :internal:
396
397Global GTT Fence Handling
398~~~~~~~~~~~~~~~~~~~~~~~~~
399
400.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
401   :doc: fence register handling
402
403Hardware Tiling and Swizzling Details
404~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
405
406.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
407   :doc: tiling swizzling details
408
409Object Tiling IOCTLs
410--------------------
411
412.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
413   :internal:
414
415.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
416   :doc: buffer object tiling
417
418WOPCM
419=====
420
421WOPCM Layout
422------------
423
424.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c
425   :doc: WOPCM Layout
426
427GuC
428===
429
430Firmware Layout
431-------------------
432
433.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h
434   :doc: Firmware Layout
435
436GuC-specific firmware loader
437----------------------------
438
439.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
440   :internal:
441
442GuC-based command submission
443----------------------------
444
445.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
446   :doc: GuC-based command submission
447
448.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
449   :internal:
450
451GuC Address Space
452-----------------
453
454.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
455   :doc: GuC Address Space
456
457Tracing
458=======
459
460This sections covers all things related to the tracepoints implemented
461in the i915 driver.
462
463i915_ppgtt_create and i915_ppgtt_release
464----------------------------------------
465
466.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
467   :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints
468
469i915_context_create and i915_context_free
470-----------------------------------------
471
472.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
473   :doc: i915_context_create and i915_context_free tracepoints
474
475Perf
476====
477
478Overview
479--------
480.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
481   :doc: i915 Perf Overview
482
483Comparison with Core Perf
484-------------------------
485.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
486   :doc: i915 Perf History and Comparison with Core Perf
487
488i915 Driver Entry Points
489------------------------
490
491This section covers the entrypoints exported outside of i915_perf.c to
492integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl.
493
494.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
495   :functions: i915_perf_init
496.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
497   :functions: i915_perf_fini
498.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
499   :functions: i915_perf_register
500.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
501   :functions: i915_perf_unregister
502.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
503   :functions: i915_perf_open_ioctl
504.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
505   :functions: i915_perf_release
506.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
507   :functions: i915_perf_add_config_ioctl
508.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
509   :functions: i915_perf_remove_config_ioctl
510
511i915 Perf Stream
512----------------
513
514This section covers the stream-semantics-agnostic structures and functions
515for representing an i915 perf stream FD and associated file operations.
516
517.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
518   :functions: i915_perf_stream
519.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
520   :functions: i915_perf_stream_ops
521
522.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
523   :functions: read_properties_unlocked
524.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
525   :functions: i915_perf_open_ioctl_locked
526.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
527   :functions: i915_perf_destroy_locked
528.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
529   :functions: i915_perf_read
530.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
531   :functions: i915_perf_ioctl
532.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
533   :functions: i915_perf_enable_locked
534.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
535   :functions: i915_perf_disable_locked
536.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
537   :functions: i915_perf_poll
538.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
539   :functions: i915_perf_poll_locked
540
541i915 Perf Observation Architecture Stream
542-----------------------------------------
543
544.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
545   :functions: i915_oa_ops
546
547.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
548   :functions: i915_oa_stream_init
549.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
550   :functions: i915_oa_read
551.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
552   :functions: i915_oa_stream_enable
553.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
554   :functions: i915_oa_stream_disable
555.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
556   :functions: i915_oa_wait_unlocked
557.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
558   :functions: i915_oa_poll_wait
559
560All i915 Perf Internals
561-----------------------
562
563This section simply includes all currently documented i915 perf internals, in
564no particular order, but may include some more minor utilities or platform
565specific details than found in the more high-level sections.
566
567.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
568   :internal:
569
570Style
571=====
572
573The drm/i915 driver codebase has some style rules in addition to (and, in some
574cases, deviating from) the kernel coding style.
575
576Register macro definition style
577-------------------------------
578
579The style guide for ``i915_reg.h``.
580
581.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
582   :doc: The i915 register macro definition style guide
583