1 2.. _drm/i915: 3 4=========================== 5 drm/i915 Intel GFX Driver 6=========================== 7 8The drm/i915 driver supports all (with the exception of some very early 9models) integrated GFX chipsets with both Intel display and rendering 10blocks. This excludes a set of SoC platforms with an SGX rendering unit, 11those have basic support through the gma500 drm driver. 12 13The display, or :ref:`drm-kms`, support for drm/i915 is provided by 14:ref:`drm/intel-display`, and shared with :ref:`drm/xe <drm/xe>`. 15 16Core Driver Infrastructure 17========================== 18 19This section covers core driver infrastructure used by both the display 20and the GEM parts of the driver. 21 22Runtime Power Management 23------------------------ 24 25.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c 26 :doc: runtime pm 27 28.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c 29 :internal: 30 31.. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c 32 :internal: 33 34Interrupt Handling 35------------------ 36 37.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c 38 :doc: interrupt handling 39 40.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c 41 :functions: intel_irq_init intel_irq_init_hw intel_hpd_init 42 43.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c 44 :functions: intel_irq_suspend 45 46.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c 47 :functions: intel_irq_resume 48 49Intel GVT-g Guest Support(vGPU) 50------------------------------- 51 52.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c 53 :doc: Intel GVT-g guest support 54 55.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c 56 :internal: 57 58Intel GVT-g Host Support(vGPU device model) 59------------------------------------------- 60 61.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c 62 :doc: Intel GVT-g host support 63 64.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c 65 :internal: 66 67Workarounds 68----------- 69 70.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c 71 :doc: Hardware workarounds 72 73GT Programming 74============== 75 76Multicast/Replicated (MCR) Registers 77------------------------------------ 78 79.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c 80 :doc: GT Multicast/Replicated (MCR) Register Support 81 82.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c 83 :internal: 84 85Memory Management and Command Submission 86======================================== 87 88This sections covers all things related to the GEM implementation in the 89i915 driver. 90 91Intel GPU Basics 92---------------- 93 94An Intel GPU has multiple engines. There are several engine types: 95 96- Render Command Streamer (RCS). An engine for rendering 3D and 97 performing compute. 98- Blitting Command Streamer (BCS). An engine for performing blitting and/or 99 copying operations. 100- Video Command Streamer. An engine used for video encoding and decoding. Also 101 sometimes called 'BSD' in hardware documentation. 102- Video Enhancement Command Streamer (VECS). An engine for video enhancement. 103 Also sometimes called 'VEBOX' in hardware documentation. 104- Compute Command Streamer (CCS). An engine that has access to the media and 105 GPGPU pipelines, but not the 3D pipeline. 106- Graphics Security Controller (GSCCS). A dedicated engine for internal 107 communication with GSC controller on security related tasks like 108 High-bandwidth Digital Content Protection (HDCP), Protected Xe Path (PXP), 109 and HuC firmware authentication. 110 111The Intel GPU family is a family of integrated GPU's using Unified 112Memory Access. For having the GPU "do work", user space will feed the 113GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2` 114or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will 115instruct the GPU to perform work (for example rendering) and that work 116needs memory from which to read and memory to which to write. All memory 117is encapsulated within GEM buffer objects (usually created with the ioctl 118`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU 119to create will also list all GEM buffer objects that the batchbuffer reads 120and/or writes. For implementation details of memory management see 121`GEM BO Management Implementation Details`_. 122 123The i915 driver allows user space to create a context via the ioctl 124`DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit 125integer. Such a context should be viewed by user-space as -loosely- 126analogous to the idea of a CPU process of an operating system. The i915 127driver guarantees that commands issued to a fixed context are to be 128executed so that writes of a previously issued command are seen by 129reads of following commands. Actions issued between different contexts 130(even if from the same file descriptor) are NOT given that guarantee 131and the only way to synchronize across contexts (even from the same 132file descriptor) is through the use of fences. At least as far back as 133Gen4, also have that a context carries with it a GPU HW context; 134the HW context is essentially (most of at least) the state of a GPU. 135In addition to the ordering guarantees, the kernel will restore GPU 136state via HW context when commands are issued to a context, this saves 137user space the need to restore (most of at least) the GPU state at the 138start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer 139work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1) 140to identify what context to use with the command. 141 142The GPU has its own memory management and address space. The kernel 143driver maintains the memory translation table for the GPU. For older 144GPUs (i.e. those before Gen8), there is a single global such translation 145table, a global Graphics Translation Table (GTT). For newer generation 146GPUs each context has its own translation table, called Per-Process 147Graphics Translation Table (PPGTT). Of important note, is that although 148PPGTT is named per-process it is actually per context. When user space 149submits a batchbuffer, the kernel walks the list of GEM buffer objects 150used by the batchbuffer and guarantees that not only is the memory of 151each such GEM buffer object resident but it is also present in the 152(PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT, 153then it is given an address. Two consequences of this are: the kernel 154needs to edit the batchbuffer submitted to write the correct value of 155the GPU address when a GEM BO is assigned a GPU address and the kernel 156might evict a different GEM BO from the (PP)GTT to make address room 157for another GEM BO. Consequently, the ioctls submitting a batchbuffer 158for execution also include a list of all locations within buffers that 159refer to GPU-addresses so that the kernel can edit the buffer correctly. 160This process is dubbed relocation. 161 162Locking Guidelines 163------------------ 164 165.. note:: 166 This is a description of how the locking should be after 167 refactoring is done. Does not necessarily reflect what the locking 168 looks like while WIP. 169 170#. All locking rules and interface contracts with cross-driver interfaces 171 (dma-buf, dma_fence) need to be followed. 172 173#. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx 174 is to be hoisted at highest level and passed down within i915_gem_ctx 175 in the call chain 176 177#. While holding lru/memory manager (buddy, drm_mm, whatever) locks 178 system memory allocations are not allowed 179 180#. Do not nest different lru/memory manager locks within each other. 181 Take them in turn to update memory allocations, relying on the object’s 182 dma_resv ww_mutex to serialize against other operations. 183 184#. The suggestion for lru/memory managers locks is that they are small 185 enough to be spinlocks. 186 187#. All features need to come with exhaustive kernel selftests and/or 188 IGT tests when appropriate 189 190#. All LMEM uAPI paths need to be fully restartable (_interruptible() 191 for all locks/waits/sleeps) 192 193 * Error handling validation through signal injection. 194 Still the best strategy we have for validating GEM uAPI 195 corner cases. 196 Must be excessively used in the IGT, and we need to check 197 that we really have full path coverage of all error cases. 198 199 * -EDEADLK handling with ww_mutex 200 201GEM BO Management Implementation Details 202---------------------------------------- 203 204.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h 205 :doc: Virtual Memory Address 206 207Buffer Object Eviction 208---------------------- 209 210This section documents the interface functions for evicting buffer 211objects to make space available in the virtual gpu address spaces. Note 212that this is mostly orthogonal to shrinking buffer objects caches, which 213has the goal to make main memory (shared with the gpu through the 214unified memory architecture) available. 215 216.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c 217 :internal: 218 219Buffer Object Memory Shrinking 220------------------------------ 221 222This section documents the interface function for shrinking memory usage 223of buffer object caches. Shrinking is used to make main memory 224available. Note that this is mostly orthogonal to evicting buffer 225objects, which has the goal to make space in gpu virtual address spaces. 226 227.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c 228 :internal: 229 230Batchbuffer Parsing 231------------------- 232 233.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c 234 :doc: batch buffer command parser 235 236.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c 237 :internal: 238 239User Batchbuffer Execution 240-------------------------- 241 242.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h 243 244.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c 245 :doc: User command execution 246 247Scheduling 248---------- 249.. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h 250 :functions: i915_sched_engine 251 252Logical Rings, Logical Ring Contexts and Execlists 253-------------------------------------------------- 254 255.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_execlists_submission.c 256 :doc: Logical Rings, Logical Ring Contexts and Execlists 257 258Global GTT views 259---------------- 260 261.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h 262 :doc: Global GTT views 263 264.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c 265 :internal: 266 267GTT Fences and Swizzling 268------------------------ 269 270.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c 271 :internal: 272 273Global GTT Fence Handling 274~~~~~~~~~~~~~~~~~~~~~~~~~ 275 276.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c 277 :doc: fence register handling 278 279Hardware Tiling and Swizzling Details 280~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 281 282.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c 283 :doc: tiling swizzling details 284 285Object Tiling IOCTLs 286-------------------- 287 288.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c 289 :internal: 290 291.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c 292 :doc: buffer object tiling 293 294Protected Objects 295----------------- 296 297.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp.c 298 :doc: PXP 299 300.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h 301 302Microcontrollers 303================ 304 305Starting from gen9, three microcontrollers are available on the HW: the 306graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the 307display microcontroller (DMC). The driver is responsible for loading the 308firmwares on the microcontrollers; the GuC and HuC firmwares are transferred 309to WOPCM using the DMA engine, while the DMC firmware is written through MMIO. 310 311WOPCM 312----- 313 314WOPCM Layout 315~~~~~~~~~~~~ 316 317.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_wopcm.c 318 :doc: WOPCM Layout 319 320GuC 321--- 322 323.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c 324 :doc: GuC 325 326.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h 327 328GuC Firmware Layout 329~~~~~~~~~~~~~~~~~~~ 330 331.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h 332 :doc: Firmware Layout 333 334GuC Memory Management 335~~~~~~~~~~~~~~~~~~~~~ 336 337.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c 338 :doc: GuC Memory Management 339.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c 340 :functions: intel_guc_allocate_vma 341 342 343GuC-specific firmware loader 344~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 345 346.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c 347 :internal: 348 349GuC-based command submission 350~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 351 352.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c 353 :doc: GuC-based command submission 354 355GuC ABI 356~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 357 358.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_messages_abi.h 359.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h 360.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h 361.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_abi.h 362.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_klvs_abi.h 363 364HuC 365--- 366.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c 367 :doc: HuC 368.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c 369 :functions: intel_huc_auth 370 371HuC Memory Management 372~~~~~~~~~~~~~~~~~~~~~ 373 374.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c 375 :doc: HuC Memory Management 376 377HuC Firmware Layout 378~~~~~~~~~~~~~~~~~~~ 379The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_ 380 381DMC 382--- 383See :ref:`drm/intel-display/dmc`. 384 385Tracing 386======= 387 388This sections covers all things related to the tracepoints implemented 389in the i915 driver. 390 391i915_ppgtt_create and i915_ppgtt_release 392---------------------------------------- 393 394.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h 395 :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints 396 397i915_context_create and i915_context_free 398----------------------------------------- 399 400.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h 401 :doc: i915_context_create and i915_context_free tracepoints 402 403Perf 404==== 405 406Overview 407-------- 408.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 409 :doc: i915 Perf Overview 410 411Comparison with Core Perf 412------------------------- 413.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 414 :doc: i915 Perf History and Comparison with Core Perf 415 416i915 Driver Entry Points 417------------------------ 418 419This section covers the entrypoints exported outside of i915_perf.c to 420integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl. 421 422.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 423 :functions: i915_perf_init 424.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 425 :functions: i915_perf_fini 426.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 427 :functions: i915_perf_register 428.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 429 :functions: i915_perf_unregister 430.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 431 :functions: i915_perf_open_ioctl 432.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 433 :functions: i915_perf_release 434.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 435 :functions: i915_perf_add_config_ioctl 436.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 437 :functions: i915_perf_remove_config_ioctl 438 439i915 Perf Stream 440---------------- 441 442This section covers the stream-semantics-agnostic structures and functions 443for representing an i915 perf stream FD and associated file operations. 444 445.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h 446 :functions: i915_perf_stream 447.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h 448 :functions: i915_perf_stream_ops 449 450.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 451 :functions: read_properties_unlocked 452.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 453 :functions: i915_perf_open_ioctl_locked 454.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 455 :functions: i915_perf_destroy_locked 456.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 457 :functions: i915_perf_read 458.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 459 :functions: i915_perf_ioctl 460.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 461 :functions: i915_perf_enable_locked 462.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 463 :functions: i915_perf_disable_locked 464.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 465 :functions: i915_perf_poll 466.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 467 :functions: i915_perf_poll_locked 468 469i915 Perf Observation Architecture Stream 470----------------------------------------- 471 472.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h 473 :functions: i915_oa_ops 474 475.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 476 :functions: i915_oa_stream_init 477.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 478 :functions: i915_oa_read 479.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 480 :functions: i915_oa_stream_enable 481.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 482 :functions: i915_oa_stream_disable 483.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 484 :functions: i915_oa_wait_unlocked 485.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 486 :functions: i915_oa_poll_wait 487 488Other i915 Perf Internals 489------------------------- 490 491This section simply includes all other currently documented i915 perf internals, 492in no particular order, but may include some more minor utilities or platform 493specific details than found in the more high-level sections. 494 495.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c 496 :internal: 497 :no-identifiers: 498 i915_perf_init 499 i915_perf_fini 500 i915_perf_register 501 i915_perf_unregister 502 i915_perf_open_ioctl 503 i915_perf_release 504 i915_perf_add_config_ioctl 505 i915_perf_remove_config_ioctl 506 read_properties_unlocked 507 i915_perf_open_ioctl_locked 508 i915_perf_destroy_locked 509 i915_perf_read i915_perf_ioctl 510 i915_perf_enable_locked 511 i915_perf_disable_locked 512 i915_perf_poll i915_perf_poll_locked 513 i915_oa_stream_init i915_oa_read 514 i915_oa_stream_enable 515 i915_oa_stream_disable 516 i915_oa_wait_unlocked 517 i915_oa_poll_wait 518 519Style 520===== 521 522The drm/i915 driver codebase has some style rules in addition to (and, in some 523cases, deviating from) the kernel coding style. 524 525Register macro definition style 526------------------------------- 527 528The style guide for ``i915_reg.h``. 529 530.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h 531 :doc: The i915 register macro definition style guide 532 533.. _i915-usage-stats: 534 535i915 DRM client usage stats implementation 536========================================== 537 538The drm/i915 driver implements the DRM client usage stats specification as 539documented in :ref:`drm-client-usage-stats`. 540 541Example of the output showing the implemented key value pairs and entirety of 542the currently possible format options: 543 544:: 545 546 pos: 0 547 flags: 0100002 548 mnt_id: 21 549 drm-driver: i915 550 drm-pdev: 0000:00:02.0 551 drm-client-id: 7 552 drm-engine-render: 9288864723 ns 553 drm-engine-copy: 2035071108 ns 554 drm-engine-video: 0 ns 555 drm-engine-capacity-video: 2 556 drm-engine-video-enhance: 0 ns 557 558Possible `drm-engine-` key names are: `render`, `copy`, `video` and 559`video-enhance`. 560