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