forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-02-20 ea08eeccae9297f7aabd2ef7f0c2517ac4549acc 
 kernel/Documentation/gpu/i915.rst
....@@ -61,7 +61,7 @@
6161 Workarounds
6262 -----------
6363 
64
-.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c
64
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
6565    :doc: Hardware workarounds
6666 
6767 Display Hardware Handling
....@@ -82,25 +82,22 @@
8282 Frontbuffer Tracking
8383 --------------------
8484 
85
-.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c
85
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
8686    :doc: frontbuffer tracking
8787 
88
-.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.h
88
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h
8989    :internal:
9090 
91
-.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c
91
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
9292    :internal:
93
-
94
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
95
-   :functions: i915_gem_track_fb
9693 
9794 Display FIFO Underrun Reporting
9895 -------------------------------
9996 
100
-.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c
97
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
10198    :doc: fifo underrun handling
10299 
103
-.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c
100
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
104101    :internal:
105102 
106103 Plane Configuration
....@@ -115,10 +112,10 @@
115112 Atomic Plane Helpers
116113 --------------------
117114 
118
-.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c
115
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
119116    :doc: atomic plane helpers
120117 
121
-.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c
118
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c
122119    :internal:
123120 
124121 Output Probing
....@@ -132,19 +129,19 @@
132129 Hotplug
133130 -------
134131 
135
-.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c
132
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
136133    :doc: Hotplug
137134 
138
-.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c
135
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
139136    :internal:
140137 
141138 High Definition Audio
142139 ---------------------
143140 
144
-.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
141
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
145142    :doc: High Definition Audio over HDMI and Display Port
146143 
147
-.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
144
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
148145    :internal:
149146 
150147 .. kernel-doc:: include/drm/i915_component.h
....@@ -153,100 +150,109 @@
153150 Intel HDMI LPE Audio Support
154151 ----------------------------
155152 
156
-.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c
153
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
157154    :doc: LPE Audio integration for HDMI or DP playback
158155 
159
-.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c
156
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
160157    :internal:
161158 
162159 Panel Self Refresh PSR (PSR/SRD)
163160 --------------------------------
164161 
165
-.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c
162
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
166163    :doc: Panel Self Refresh (PSR/SRD)
167164 
168
-.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c
165
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
169166    :internal:
170167 
171168 Frame Buffer Compression (FBC)
172169 ------------------------------
173170 
174
-.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c
171
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
175172    :doc: Frame Buffer Compression (FBC)
176173 
177
-.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c
174
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
178175    :internal:
179176 
180177 Display Refresh Rate Switching (DRRS)
181178 -------------------------------------
182179 
183
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
180
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
184181    :doc: Display Refresh Rate Switching (DRRS)
185182 
186
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
183
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
187184    :functions: intel_dp_set_drrs_state
188185 
189
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
186
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
190187    :functions: intel_edp_drrs_enable
191188 
192
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
189
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
193190    :functions: intel_edp_drrs_disable
194191 
195
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
192
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
196193    :functions: intel_edp_drrs_invalidate
197194 
198
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
195
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
199196    :functions: intel_edp_drrs_flush
200197 
201
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
198
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
202199    :functions: intel_dp_drrs_init
203200 
204201 DPIO
205202 ----
206203 
207
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dpio_phy.c
204
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
208205    :doc: DPIO
209206 
210207 CSR firmware support for DMC
211208 ----------------------------
212209 
213
-.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
210
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_csr.c
214211    :doc: csr support for dmc
215212 
216
-.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
213
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_csr.c
217214    :internal:
218215 
219216 Video BIOS Table (VBT)
220217 ----------------------
221218 
222
-.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c
219
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
223220    :doc: Video BIOS Table (VBT)
224221 
225
-.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c
222
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
226223    :internal:
227224 
228
-.. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h
225
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h
229226    :internal:
230227 
231228 Display clocks
232229 --------------
233230 
234
-.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c
231
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
235232    :doc: CDCLK / RAWCLK
236233 
237
-.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c
234
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
238235    :internal:
239236 
240237 Display PLLs
241238 ------------
242239 
243
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c
240
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
244241    :doc: Display PLLs
245242 
246
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c
243
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
247244    :internal:
248245 
249
-.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.h
246
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
247
+   :internal:
248
+
249
+Display State Buffer
250
+--------------------
251
+
252
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
253
+   :doc: DSB
254
+
255
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
250256    :internal:
251257 
252258 Memory Management and Command Submission
....@@ -323,10 +329,56 @@
323329 refer to GPU-addresses so that the kernel can edit the buffer correctly.
324330 This process is dubbed relocation.
325331 
332
+Locking Guidelines
333
+------------------
334
+
335
+.. note::
336
+   This is a description of how the locking should be after
337
+   refactoring is done. Does not necessarily reflect what the locking
338
+   looks like while WIP.
339
+
340
+#. All locking rules and interface contracts with cross-driver interfaces
341
+   (dma-buf, dma_fence) need to be followed.
342
+
343
+#. No struct_mutex anywhere in the code
344
+
345
+#. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx
346
+   is to be hoisted at highest level and passed down within i915_gem_ctx
347
+   in the call chain
348
+
349
+#. While holding lru/memory manager (buddy, drm_mm, whatever) locks
350
+   system memory allocations are not allowed
351
+
352
+	* Enforce this by priming lockdep (with fs_reclaim). If we
353
+	  allocate memory while holding these looks we get a rehash
354
+	  of the shrinker vs. struct_mutex saga, and that would be
355
+	  real bad.
356
+
357
+#. Do not nest different lru/memory manager locks within each other.
358
+   Take them in turn to update memory allocations, relying on the object’s
359
+   dma_resv ww_mutex to serialize against other operations.
360
+
361
+#. The suggestion for lru/memory managers locks is that they are small
362
+   enough to be spinlocks.
363
+
364
+#. All features need to come with exhaustive kernel selftests and/or
365
+   IGT tests when appropriate
366
+
367
+#. All LMEM uAPI paths need to be fully restartable (_interruptible()
368
+   for all locks/waits/sleeps)
369
+
370
+	* Error handling validation through signal injection.
371
+	  Still the best strategy we have for validating GEM uAPI
372
+          corner cases.
373
+	  Must be excessively used in the IGT, and we need to check
374
+	  that we really have full path coverage of all error cases.
375
+
376
+	* -EDEADLK handling with ww_mutex
377
+
326378 GEM BO Management Implementation Details
327379 ----------------------------------------
328380 
329
-.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
381
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h
330382    :doc: Virtual Memory Address
331383 
332384 Buffer Object Eviction
....@@ -349,7 +401,7 @@
349401 available. Note that this is mostly orthogonal to evicting buffer
350402 objects, which has the goal to make space in gpu virtual address spaces.
351403 
352
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c
404
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
353405    :internal:
354406 
355407 Batchbuffer Parsing
....@@ -361,34 +413,22 @@
361413 .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
362414    :internal:
363415 
364
-Batchbuffer Pools
365
------------------
366
-
367
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
368
-   :doc: batch pool
369
-
370
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
371
-   :internal:
372
-
373416 User Batchbuffer Execution
374417 --------------------------
375418 
376
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_execbuffer.c
419
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
377420    :doc: User command execution
378421 
379422 Logical Rings, Logical Ring Contexts and Execlists
380423 --------------------------------------------------
381424 
382
-.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c
425
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c
383426    :doc: Logical Rings, Logical Ring Contexts and Execlists
384
-
385
-.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c
386
-   :internal:
387427 
388428 Global GTT views
389429 ----------------
390430 
391
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
431
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h
392432    :doc: Global GTT views
393433 
394434 .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
....@@ -397,68 +437,101 @@
397437 GTT Fences and Swizzling
398438 ------------------------
399439 
400
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
440
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
401441    :internal:
402442 
403443 Global GTT Fence Handling
404444 ~~~~~~~~~~~~~~~~~~~~~~~~~
405445 
406
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
446
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
407447    :doc: fence register handling
408448 
409449 Hardware Tiling and Swizzling Details
410450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411451 
412
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
452
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c
413453    :doc: tiling swizzling details
414454 
415455 Object Tiling IOCTLs
416456 --------------------
417457 
418
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c
458
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
419459    :internal:
420460 
421
-.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c
461
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
422462    :doc: buffer object tiling
423463 
464
+Microcontrollers
465
+================
466
+
467
+Starting from gen9, three microcontrollers are available on the HW: the
468
+graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the
469
+display microcontroller (DMC). The driver is responsible for loading the
470
+firmwares on the microcontrollers; the GuC and HuC firmwares are transferred
471
+to WOPCM using the DMA engine, while the DMC firmware is written through MMIO.
472
+
424473 WOPCM
425
-=====
474
+-----
426475 
427476 WOPCM Layout
428
-------------
477
+~~~~~~~~~~~~
429478 
430479 .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c
431480    :doc: WOPCM Layout
432481 
433482 GuC
434
-===
483
+---
484
+
485
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
486
+   :doc: GuC
487
+
488
+GuC Firmware Layout
489
+~~~~~~~~~~~~~~~~~~~
490
+
491
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h
492
+   :doc: Firmware Layout
493
+
494
+GuC Memory Management
495
+~~~~~~~~~~~~~~~~~~~~~
496
+
497
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
498
+   :doc: GuC Memory Management
499
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
500
+   :functions: intel_guc_allocate_vma
501
+
435502 
436503 GuC-specific firmware loader
437
-----------------------------
504
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
438505 
439
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c
506
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c
440507    :internal:
441508 
442509 GuC-based command submission
443
-----------------------------
510
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
444511 
445
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
512
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c
446513    :doc: GuC-based command submission
447514 
448
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
449
-   :internal:
515
+HuC
516
+---
517
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
518
+   :doc: HuC
519
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
520
+   :functions: intel_huc_auth
450521 
451
-GuC Firmware Layout
452
--------------------
522
+HuC Memory Management
523
+~~~~~~~~~~~~~~~~~~~~~
453524 
454
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h
455
-   :doc: GuC Firmware Layout
525
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c
526
+   :doc: HuC Memory Management
456527 
457
-GuC Address Space
458
------------------
528
+HuC Firmware Layout
529
+~~~~~~~~~~~~~~~~~~~
530
+The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_
459531 
460
-.. kernel-doc:: drivers/gpu/drm/i915/intel_guc.c
461
-   :doc: GuC Address Space
532
+DMC
533
+---
534
+See `CSR firmware support for DMC`_
462535 
463536 Tracing
464537 =======
....@@ -477,12 +550,6 @@
477550 
478551 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
479552    :doc: i915_context_create and i915_context_free tracepoints
480
-
481
-switch_mm
482
----------
483
-
484
-.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
485
-   :doc: switch_mm tracepoint
486553 
487554 Perf
488555 ====
....@@ -526,9 +593,9 @@
526593 This section covers the stream-semantics-agnostic structures and functions
527594 for representing an i915 perf stream FD and associated file operations.
528595 
529
-.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
596
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
530597    :functions: i915_perf_stream
531
-.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
598
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
532599    :functions: i915_perf_stream_ops
533600 
534601 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
....@@ -553,7 +620,7 @@
553620 i915 Perf Observation Architecture Stream
554621 -----------------------------------------
555622 
556
-.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
623
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h
557624    :functions: i915_oa_ops
558625 
559626 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
....@@ -569,15 +636,36 @@
569636 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
570637    :functions: i915_oa_poll_wait
571638 
572
-All i915 Perf Internals
573
------------------------
639
+Other i915 Perf Internals
640
+-------------------------
574641 
575
-This section simply includes all currently documented i915 perf internals, in
576
-no particular order, but may include some more minor utilities or platform
642
+This section simply includes all other currently documented i915 perf internals,
643
+in no particular order, but may include some more minor utilities or platform
577644 specific details than found in the more high-level sections.
578645 
579646 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
580647    :internal:
648
+   :no-identifiers:
649
+       i915_perf_init
650
+       i915_perf_fini
651
+       i915_perf_register
652
+       i915_perf_unregister
653
+       i915_perf_open_ioctl
654
+       i915_perf_release
655
+       i915_perf_add_config_ioctl
656
+       i915_perf_remove_config_ioctl
657
+       read_properties_unlocked
658
+       i915_perf_open_ioctl_locked
659
+       i915_perf_destroy_locked
660
+       i915_perf_read i915_perf_ioctl
661
+       i915_perf_enable_locked
662
+       i915_perf_disable_locked
663
+       i915_perf_poll i915_perf_poll_locked
664
+       i915_oa_stream_init i915_oa_read
665
+       i915_oa_stream_enable
666
+       i915_oa_stream_disable
667
+       i915_oa_wait_unlocked
668
+       i915_oa_poll_wait
581669 
582670 Style
583671 =====