| .. _drm/i915: | |
| =========================== | |
| drm/i915 Intel GFX Driver | |
| =========================== | |
| The drm/i915 driver supports all (with the exception of some very early | |
| models) integrated GFX chipsets with both Intel display and rendering | |
| blocks. This excludes a set of SoC platforms with an SGX rendering unit, | |
| those have basic support through the gma500 drm driver. | |
| The display, or :ref:`drm-kms`, support for drm/i915 is provided by | |
| :ref:`drm/intel-display`, and shared with :ref:`drm/xe <drm/xe>`. | |
| Core Driver Infrastructure | |
| ========================== | |
| This section covers core driver infrastructure used by both the display | |
| and the GEM parts of the driver. | |
| Runtime Power Management | |
| ------------------------ | |
| .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c | |
| :doc: runtime pm | |
| .. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c | |
| :internal: | |
| .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c | |
| :internal: | |
| Interrupt Handling | |
| ------------------ | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
| :doc: interrupt handling | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
| :functions: intel_irq_init intel_irq_init_hw intel_hpd_init | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
| :functions: intel_irq_suspend | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c | |
| :functions: intel_irq_resume | |
| Intel GVT-g Guest Support(vGPU) | |
| ------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c | |
| :doc: Intel GVT-g guest support | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c | |
| :internal: | |
| Intel GVT-g Host Support(vGPU device model) | |
| ------------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c | |
| :doc: Intel GVT-g host support | |
| .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c | |
| :internal: | |
| Workarounds | |
| ----------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c | |
| :doc: Hardware workarounds | |
| GT Programming | |
| ============== | |
| Multicast/Replicated (MCR) Registers | |
| ------------------------------------ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c | |
| :doc: GT Multicast/Replicated (MCR) Register Support | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c | |
| :internal: | |
| Memory Management and Command Submission | |
| ======================================== | |
| This sections covers all things related to the GEM implementation in the | |
| i915 driver. | |
| Intel GPU Basics | |
| ---------------- | |
| An Intel GPU has multiple engines. There are several engine types: | |
| - Render Command Streamer (RCS). An engine for rendering 3D and | |
| performing compute. | |
| - Blitting Command Streamer (BCS). An engine for performing blitting and/or | |
| copying operations. | |
| - Video Command Streamer. An engine used for video encoding and decoding. Also | |
| sometimes called 'BSD' in hardware documentation. | |
| - Video Enhancement Command Streamer (VECS). An engine for video enhancement. | |
| Also sometimes called 'VEBOX' in hardware documentation. | |
| - Compute Command Streamer (CCS). An engine that has access to the media and | |
| GPGPU pipelines, but not the 3D pipeline. | |
| - Graphics Security Controller (GSCCS). A dedicated engine for internal | |
| communication with GSC controller on security related tasks like | |
| High-bandwidth Digital Content Protection (HDCP), Protected Xe Path (PXP), | |
| and HuC firmware authentication. | |
| The Intel GPU family is a family of integrated GPU's using Unified | |
| Memory Access. For having the GPU "do work", user space will feed the | |
| GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2` | |
| or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will | |
| instruct the GPU to perform work (for example rendering) and that work | |
| needs memory from which to read and memory to which to write. All memory | |
| is encapsulated within GEM buffer objects (usually created with the ioctl | |
| `DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU | |
| to create will also list all GEM buffer objects that the batchbuffer reads | |
| and/or writes. For implementation details of memory management see | |
| `GEM BO Management Implementation Details`_. | |
| The i915 driver allows user space to create a context via the ioctl | |
| `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit | |
| integer. Such a context should be viewed by user-space as -loosely- | |
| analogous to the idea of a CPU process of an operating system. The i915 | |
| driver guarantees that commands issued to a fixed context are to be | |
| executed so that writes of a previously issued command are seen by | |
| reads of following commands. Actions issued between different contexts | |
| (even if from the same file descriptor) are NOT given that guarantee | |
| and the only way to synchronize across contexts (even from the same | |
| file descriptor) is through the use of fences. At least as far back as | |
| Gen4, also have that a context carries with it a GPU HW context; | |
| the HW context is essentially (most of at least) the state of a GPU. | |
| In addition to the ordering guarantees, the kernel will restore GPU | |
| state via HW context when commands are issued to a context, this saves | |
| user space the need to restore (most of at least) the GPU state at the | |
| start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer | |
| work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1) | |
| to identify what context to use with the command. | |
| The GPU has its own memory management and address space. The kernel | |
| driver maintains the memory translation table for the GPU. For older | |
| GPUs (i.e. those before Gen8), there is a single global such translation | |
| table, a global Graphics Translation Table (GTT). For newer generation | |
| GPUs each context has its own translation table, called Per-Process | |
| Graphics Translation Table (PPGTT). Of important note, is that although | |
| PPGTT is named per-process it is actually per context. When user space | |
| submits a batchbuffer, the kernel walks the list of GEM buffer objects | |
| used by the batchbuffer and guarantees that not only is the memory of | |
| each such GEM buffer object resident but it is also present in the | |
| (PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT, | |
| then it is given an address. Two consequences of this are: the kernel | |
| needs to edit the batchbuffer submitted to write the correct value of | |
| the GPU address when a GEM BO is assigned a GPU address and the kernel | |
| might evict a different GEM BO from the (PP)GTT to make address room | |
| for another GEM BO. Consequently, the ioctls submitting a batchbuffer | |
| for execution also include a list of all locations within buffers that | |
| refer to GPU-addresses so that the kernel can edit the buffer correctly. | |
| This process is dubbed relocation. | |
| Locking Guidelines | |
| ------------------ | |
| .. note:: | |
| This is a description of how the locking should be after | |
| refactoring is done. Does not necessarily reflect what the locking | |
| looks like while WIP. | |
| #. All locking rules and interface contracts with cross-driver interfaces | |
| (dma-buf, dma_fence) need to be followed. | |
| #. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx | |
| is to be hoisted at highest level and passed down within i915_gem_ctx | |
| in the call chain | |
| #. While holding lru/memory manager (buddy, drm_mm, whatever) locks | |
| system memory allocations are not allowed | |
| #. Do not nest different lru/memory manager locks within each other. | |
| Take them in turn to update memory allocations, relying on the object’s | |
| dma_resv ww_mutex to serialize against other operations. | |
| #. The suggestion for lru/memory managers locks is that they are small | |
| enough to be spinlocks. | |
| #. All features need to come with exhaustive kernel selftests and/or | |
| IGT tests when appropriate | |
| #. All LMEM uAPI paths need to be fully restartable (_interruptible() | |
| for all locks/waits/sleeps) | |
| * Error handling validation through signal injection. | |
| Still the best strategy we have for validating GEM uAPI | |
| corner cases. | |
| Must be excessively used in the IGT, and we need to check | |
| that we really have full path coverage of all error cases. | |
| * -EDEADLK handling with ww_mutex | |
| GEM BO Management Implementation Details | |
| ---------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h | |
| :doc: Virtual Memory Address | |
| Buffer Object Eviction | |
| ---------------------- | |
| This section documents the interface functions for evicting buffer | |
| objects to make space available in the virtual gpu address spaces. Note | |
| that this is mostly orthogonal to shrinking buffer objects caches, which | |
| has the goal to make main memory (shared with the gpu through the | |
| unified memory architecture) available. | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c | |
| :internal: | |
| Buffer Object Memory Shrinking | |
| ------------------------------ | |
| This section documents the interface function for shrinking memory usage | |
| of buffer object caches. Shrinking is used to make main memory | |
| available. Note that this is mostly orthogonal to evicting buffer | |
| objects, which has the goal to make space in gpu virtual address spaces. | |
| .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c | |
| :internal: | |
| Batchbuffer Parsing | |
| ------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c | |
| :doc: batch buffer command parser | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c | |
| :internal: | |
| User Batchbuffer Execution | |
| -------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h | |
| .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c | |
| :doc: User command execution | |
| Scheduling | |
| ---------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h | |
| :functions: i915_sched_engine | |
| Logical Rings, Logical Ring Contexts and Execlists | |
| -------------------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_execlists_submission.c | |
| :doc: Logical Rings, Logical Ring Contexts and Execlists | |
| Global GTT views | |
| ---------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_vma_types.h | |
| :doc: Global GTT views | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c | |
| :internal: | |
| GTT Fences and Swizzling | |
| ------------------------ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c | |
| :internal: | |
| Global GTT Fence Handling | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c | |
| :doc: fence register handling | |
| Hardware Tiling and Swizzling Details | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt_fencing.c | |
| :doc: tiling swizzling details | |
| Object Tiling IOCTLs | |
| -------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c | |
| :internal: | |
| .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c | |
| :doc: buffer object tiling | |
| Protected Objects | |
| ----------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp.c | |
| :doc: PXP | |
| .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h | |
| Microcontrollers | |
| ================ | |
| Starting from gen9, three microcontrollers are available on the HW: the | |
| graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the | |
| display microcontroller (DMC). The driver is responsible for loading the | |
| firmwares on the microcontrollers; the GuC and HuC firmwares are transferred | |
| to WOPCM using the DMA engine, while the DMC firmware is written through MMIO. | |
| WOPCM | |
| ----- | |
| WOPCM Layout | |
| ~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_wopcm.c | |
| :doc: WOPCM Layout | |
| GuC | |
| --- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c | |
| :doc: GuC | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h | |
| GuC Firmware Layout | |
| ~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h | |
| :doc: Firmware Layout | |
| GuC Memory Management | |
| ~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c | |
| :doc: GuC Memory Management | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c | |
| :functions: intel_guc_allocate_vma | |
| GuC-specific firmware loader | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c | |
| :internal: | |
| GuC-based command submission | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c | |
| :doc: GuC-based command submission | |
| GuC ABI | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_messages_abi.h | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_abi.h | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_klvs_abi.h | |
| HuC | |
| --- | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c | |
| :doc: HuC | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c | |
| :functions: intel_huc_auth | |
| HuC Memory Management | |
| ~~~~~~~~~~~~~~~~~~~~~ | |
| .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c | |
| :doc: HuC Memory Management | |
| HuC Firmware Layout | |
| ~~~~~~~~~~~~~~~~~~~ | |
| The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_ | |
| DMC | |
| --- | |
| See :ref:`drm/intel-display/dmc`. | |
| Tracing | |
| ======= | |
| This sections covers all things related to the tracepoints implemented | |
| in the i915 driver. | |
| i915_ppgtt_create and i915_ppgtt_release | |
| ---------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h | |
| :doc: i915_ppgtt_create and i915_ppgtt_release tracepoints | |
| i915_context_create and i915_context_free | |
| ----------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h | |
| :doc: i915_context_create and i915_context_free tracepoints | |
| Perf | |
| ==== | |
| Overview | |
| -------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :doc: i915 Perf Overview | |
| Comparison with Core Perf | |
| ------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :doc: i915 Perf History and Comparison with Core Perf | |
| i915 Driver Entry Points | |
| ------------------------ | |
| This section covers the entrypoints exported outside of i915_perf.c to | |
| integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl. | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_init | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_fini | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_register | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_unregister | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_open_ioctl | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_release | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_add_config_ioctl | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_remove_config_ioctl | |
| i915 Perf Stream | |
| ---------------- | |
| This section covers the stream-semantics-agnostic structures and functions | |
| for representing an i915 perf stream FD and associated file operations. | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h | |
| :functions: i915_perf_stream | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h | |
| :functions: i915_perf_stream_ops | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: read_properties_unlocked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_open_ioctl_locked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_destroy_locked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_read | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_ioctl | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_enable_locked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_disable_locked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_poll | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_perf_poll_locked | |
| i915 Perf Observation Architecture Stream | |
| ----------------------------------------- | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h | |
| :functions: i915_oa_ops | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_stream_init | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_read | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_stream_enable | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_stream_disable | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_wait_unlocked | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :functions: i915_oa_poll_wait | |
| Other i915 Perf Internals | |
| ------------------------- | |
| This section simply includes all other currently documented i915 perf internals, | |
| in no particular order, but may include some more minor utilities or platform | |
| specific details than found in the more high-level sections. | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c | |
| :internal: | |
| :no-identifiers: | |
| i915_perf_init | |
| i915_perf_fini | |
| i915_perf_register | |
| i915_perf_unregister | |
| i915_perf_open_ioctl | |
| i915_perf_release | |
| i915_perf_add_config_ioctl | |
| i915_perf_remove_config_ioctl | |
| read_properties_unlocked | |
| i915_perf_open_ioctl_locked | |
| i915_perf_destroy_locked | |
| i915_perf_read i915_perf_ioctl | |
| i915_perf_enable_locked | |
| i915_perf_disable_locked | |
| i915_perf_poll i915_perf_poll_locked | |
| i915_oa_stream_init i915_oa_read | |
| i915_oa_stream_enable | |
| i915_oa_stream_disable | |
| i915_oa_wait_unlocked | |
| i915_oa_poll_wait | |
| Style | |
| ===== | |
| The drm/i915 driver codebase has some style rules in addition to (and, in some | |
| cases, deviating from) the kernel coding style. | |
| Register macro definition style | |
| ------------------------------- | |
| The style guide for ``i915_reg.h``. | |
| .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h | |
| :doc: The i915 register macro definition style guide | |
| .. _i915-usage-stats: | |
| i915 DRM client usage stats implementation | |
| ========================================== | |
| The drm/i915 driver implements the DRM client usage stats specification as | |
| documented in :ref:`drm-client-usage-stats`. | |
| Example of the output showing the implemented key value pairs and entirety of | |
| the currently possible format options: | |
| :: | |
| pos: 0 | |
| flags: 0100002 | |
| mnt_id: 21 | |
| drm-driver: i915 | |
| drm-pdev: 0000:00:02.0 | |
| drm-client-id: 7 | |
| drm-engine-render: 9288864723 ns | |
| drm-engine-copy: 2035071108 ns | |
| drm-engine-video: 0 ns | |
| drm-engine-capacity-video: 2 | |
| drm-engine-video-enhance: 0 ns | |
| Possible `drm-engine-` key names are: `render`, `copy`, `video` and | |
| `video-enhance`. |