drm/i915 Intel GFX Driver

i915 범위와 core driver infrastructure

`drm/i915` driver는 일부 극초기 model을 제외하고 Intel display block과 rendering block을 모두 갖춘 integrated GFX chipset을 지원합니다. SGX rendering unit을 사용하는 일부 SoC platform은 여기서 제외되며 기본 지원은 `gma500` DRM driver가 담당합니다.

Core driver infrastructure 절은 display와 GEM 양쪽이 함께 사용하는 기반을 다룹니다.

Runtime power management block은 `intel_runtime_pm.c`의 runtime PM 문서와 내부 구현, `intel_uncore.c` 내부 API를 연결합니다.

Interrupt handling block은 `i915_irq.c`의 전체 interrupt 설계와 `intel_irq_init`, `intel_irq_init_hw`, `intel_hpd_init`, suspend·resume entry point를 문서화합니다.

GVT-g guest support는 `i915_vgpu.c`, host-side vGPU device model은 `intel_gvt.c`의 문서와 internal API를 연결합니다. Hardware workaround는 `gt/intel_workarounds.c`가 설명합니다.

===========================
 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.

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

Display Hardware Handling

Display hardware 처리

Display hardware 절은 mode-setting infrastructure, primary plane·sprite·cursor, display output probing과 관련 주제를 모두 다룹니다.

현재까지 i915는 mode-setting sequence 구현에 공통 DRM helper code를 사용하지 않는 유일한 DRM driver입니다. 따라서 display configuration 변경을 실행하는 전용 infrastructure를 갖습니다.

Frontbuffer tracking은 `intel_frontbuffer.c`와 header의 public 설명·internal API를 연결하고, FIFO underrun reporting은 `intel_fifo_underrun.c`의 underrun 처리와 내부 함수를 다룹니다.

Plane configuration은 primary plane, sprite, cursor, overlay의 composition을 포괄합니다. 모든 state를 atomic하고 vsync에 맞춰 update하는 기반과 watermark 계산, framebuffer compression, panel self refresh처럼 긴밀히 연결된 주제를 포함합니다.

Atomic plane helper는 `intel_plane.c`, asynchronous page flip은 `intel_display.c`의 구현 문서를 사용합니다.

Output probing은 hotplug interrupt storm detection과 mitigation을 포함합니다. Mode setting과 달리 i915는 output probing에서는 공통 DRM helper 대부분을 사용하므로 해당 공통 문서도 그대로 적용됩니다.

그 밖에 HDMI·DisplayPort HDA와 LPE audio, PSR/SRD, FBC, DRRS, DPIO, DMC firmware·flip queue·wakelock, VBT, CDCLK/RAWCLK, display PLL과 DSB를 각 source의 kernel-doc에서 연결합니다.

=========================

This section covers everything related to the display hardware including
the mode setting infrastructure, plane, sprite and cursor handling and
display, output probing and related topics.

Mode Setting Infrastructure
---------------------------

The i915 driver is thus far the only DRM driver which doesn't use the
common DRM helper code to implement mode setting sequences. Thus it has
its own tailor-made infrastructure for executing a display configuration
change.

Frontbuffer Tracking
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
   :doc: frontbuffer tracking

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
   :internal:

Display FIFO Underrun Reporting
-------------------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
   :doc: fifo underrun handling

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
   :internal:

Plane Configuration
-------------------

This section covers plane configuration and composition with the primary
plane, sprites, cursors and overlays. This includes the infrastructure
to do atomic vsync'ed updates of all this state and also tightly coupled
topics like watermark setup and computation, framebuffer compression and
panel self refresh.

Atomic Plane Helpers
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_plane.c
   :doc: atomic plane helpers

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_plane.c
   :internal:

Asynchronous Page Flip
----------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
   :doc: asynchronous flip implementation

Output Probing
--------------

This section covers output probing and related infrastructure like the
hotplug interrupt storm detection and mitigation code. Note that the
i915 driver still uses most of the common DRM helper code for output
probing, so those sections fully apply.

Hotplug
-------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
   :doc: Hotplug

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
   :internal:

High Definition Audio
---------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
   :doc: High Definition Audio over HDMI and Display Port

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
   :internal:

.. kernel-doc:: include/drm/intel/i915_component.h
   :internal:

Intel HDMI LPE Audio Support
----------------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
   :doc: LPE Audio integration for HDMI or DP playback

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c
   :internal:

Panel Self Refresh PSR (PSR/SRD)
--------------------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
   :doc: Panel Self Refresh (PSR/SRD)

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
   :internal:

Frame Buffer Compression (FBC)
------------------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
   :doc: Frame Buffer Compression (FBC)

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
   :internal:

Display Refresh Rate Switching (DRRS)
-------------------------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
   :doc: Display Refresh Rate Switching (DRRS)

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
   :internal:

DPIO
----

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
   :doc: DPIO

DMC Firmware Support
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
   :doc: DMC Firmware Support

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
   :internal:

DMC Flip Queue
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_flipq.c
   :doc: DMC Flip Queue

DMC wakelock support
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc_wl.c
   :doc: DMC wakelock support

Video BIOS Table (VBT)
----------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
   :doc: Video BIOS Table (VBT)

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h
   :internal:

Display clocks
--------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
   :doc: CDCLK / RAWCLK

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
   :internal:

Display PLLs
------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
   :doc: Display PLLs

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
   :internal:

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
   :internal:

Display State Buffer
--------------------

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
   :doc: DSB

.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
   :internal:

GT Programming

GT programming, GPU 기본과 locking guideline

GT programming은 `intel_gt_mcr.c`의 multicast/replicated(MCR) register support를 문서화합니다. 이어지는 절은 i915 GEM memory management와 command submission 전반을 설명합니다.

Intel GPU에는 여러 engine type이 있습니다. RCS는 3D rendering과 compute, BCS는 blit·copy, Video Command Streamer 또는 BSD는 video encode·decode, VECS 또는 VEBOX는 video enhancement를 수행합니다. CCS는 media·GPGPU pipeline에 접근하지만 3D pipeline에는 접근하지 않습니다.

GSCCS는 GSC controller와 내부 통신하는 전용 engine으로 HDCP, Protected Xe Path(PXP), HuC firmware authentication 같은 security task를 수행합니다.

Intel integrated GPU는 Unified Memory Access를 사용합니다. Userspace는 `DRM_IOCTL_I915_GEM_EXECBUFFER2` 또는 `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`로 GPU batch buffer를 제출합니다.

Batch buffer가 읽고 쓸 memory는 GEM buffer object로 캡슐화되며 보통 `DRM_IOCTL_I915_GEM_CREATE`로 만듭니다. Submit IOCTL은 batch buffer가 접근하는 모든 GEM object 목록도 함께 전달합니다.

Userspace는 `DRM_IOCTL_I915_GEM_CONTEXT_CREATE`로 32-bit ID의 context를 만들 수 있습니다. Context는 느슨하게 CPU process와 비슷합니다. 같은 context에 issue한 command는 이전 command의 write가 뒤 command의 read에 보이도록 ordering이 보장됩니다.

서로 다른 context 사이에는 같은 file descriptor에서 왔더라도 이 ordering 보장이 없습니다. Context 사이의 유일한 synchronization 방법은 fence입니다. Gen4 이후 context는 GPU state 대부분을 담는 hardware context도 가지므로 kernel이 command 제출 시 GPU state를 restore합니다. Execbuffer2의 `drm_i915_gem_execbuffer2::rsvd1` lower bit로 context ID를 지정합니다.

GPU는 자체 address space와 memory translation table을 갖습니다. Gen8 이전에는 global GTT 하나를 사용하고, 최신 GPU는 context마다 PPGTT를 사용합니다. 이름은 per-process이지만 실제 범위는 per-context입니다.

Batch 제출 때 kernel은 GEM object 목록을 순회해 각 object memory가 resident이고 (PP)GTT에 존재하도록 보장합니다. 아직 address가 없으면 할당하며 공간을 만들려고 다른 GEM object를 evict할 수 있습니다.

Object의 GPU address가 정해지면 kernel이 batch buffer 안의 GPU address reference를 수정해야 합니다. Submit IOCTL은 이 위치 목록도 전달하며 이 과정을 relocation이라고 합니다.

Locking guideline은 refactoring 완료 후 목표 상태를 설명하며 현재 WIP code와 반드시 같지는 않습니다. Cross-driver `dma-buf`·`dma_fence` 계약을 모두 지키고, 필요할 때 `dma_resv`를 outermost lock으로 두며 `ww_acquire_ctx`를 최상위로 끌어올려 call chain의 `i915_gem_ctx`로 전달합니다.

LRU나 buddy·`drm_mm` 같은 memory-manager lock을 잡은 동안 system memory allocation을 하면 안 됩니다. 서로 다른 LRU·memory-manager lock을 중첩하지 말고 object의 dma_resv `ww_mutex`로 다른 operation과 직렬화하면서 차례로 잡아 allocation을 update합니다.

LRU·memory-manager lock은 spinlock으로 만들 만큼 작게 유지하는 것이 권장됩니다. 모든 feature에는 적절한 exhaustive kernel selftest 또는 IGT test가 필요합니다.

모든 LMEM uAPI path는 완전히 restartable해야 하며 모든 lock·wait·sleep에 `_interruptible()` variant를 사용합니다. Signal injection으로 error handling path를 광범위하게 검증하고 `ww_mutex`의 `-EDEADLK` 처리도 시험해야 합니다.

==============

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

GEM object 관리와 command submission

GEM BO implementation detail은 `i915_vma_types.h`의 virtual memory address 문서에서 시작합니다.

Buffer object eviction은 virtual GPU address space에 공간을 만들기 위한 interface입니다. Main memory를 확보하려는 buffer-object cache shrinking과 목적이 대체로 독립적입니다.

반대로 GEM shrinker는 unified memory architecture를 통해 GPU와 공유되는 main memory를 확보하며 GPU virtual address 공간 확보가 목적인 eviction과 구분됩니다.

Batchbuffer parser는 `i915_cmd_parser.c`, userspace command execution은 GEM context type과 `i915_gem_execbuffer.c`가 설명합니다. Scheduler는 `i915_sched_engine`, logical ring·context·execlist는 `intel_execlists_submission.c` 문서를 연결합니다.

GTT 관련 절은 global GTT view, GTT fence와 swizzling, fence register 처리, hardware tiling swizzle detail 및 tiling IOCTL을 포괄합니다.

Protected object는 `intel_pxp.c`와 `intel_pxp_types.h`의 PXP 문서를 연결합니다.

----------------------------------------

.. 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

GuC·HuC·DMC microcontroller

Gen9부터 hardware에는 graphics microcontroller(GuC), HEVC/H.265 microcontroller(HuC), display microcontroller(DMC) 세 종류가 있습니다.

Driver가 각 microcontroller firmware를 load합니다. GuC와 HuC firmware는 DMA engine으로 WOPCM에 전달하고 DMC firmware는 MMIO로 기록합니다.

WOPCM 절은 `intel_wopcm.c`의 layout, GuC 절은 core object와 header를 문서화합니다. Firmware layout은 `intel_uc_fw_abi.h`, GuC memory management와 `intel_guc_allocate_vma`는 `intel_guc.c`가 설명합니다.

GuC-specific loader는 `intel_guc_fw.c`, GuC-based command submission은 `intel_guc_submission.c`를 사용합니다. GuC ABI는 message, MMIO communication, CTB communication, action과 KLV header 다섯 개 source로 나뉩니다.

HuC 절은 core 문서와 `intel_huc_auth`, memory management를 포함합니다. HuC firmware layout은 GuC layout과 같습니다. DMC는 앞의 Display Hardware Handling 절에 있는 DMC Firmware Support를 참조합니다.

================

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 `DMC Firmware Support`_

Tracing

i915 tracepoint

Tracing 절은 i915 driver가 구현한 tracepoint를 다룹니다.

첫 block은 `i915_ppgtt_create`와 `i915_ppgtt_release` tracepoint로 per-context GPU address-space lifetime을 관찰합니다. 둘째 block은 `i915_context_create`와 `i915_context_free` tracepoint로 context lifetime을 추적합니다.

=======

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

i915 perf와 OA stream

Perf 절은 i915 performance monitoring overview와 core perf subsystem과의 역사·차이를 설명합니다.

Driver entry point는 `i915_perf.c` 밖으로 export되어 drm/i915에 통합되고 `DRM_I915_PERF_OPEN` ioctl을 처리하는 function입니다. Init·fini, register·unregister, open·release와 metric configuration add·remove를 포함합니다.

i915 perf stream 절은 stream semantics와 무관하게 perf stream FD와 file operation을 표현하는 structure·function을 다룹니다. Property parsing, locked open·destroy, read·ioctl, enable·disable, poll path를 연결합니다.

Observation Architecture(OA) stream은 `i915_oa_ops`와 stream init, OA read, enable·disable, wait·poll function을 문서화합니다.

Other internals block은 앞의 고수준 절에서 이미 포함한 identifier를 `:no-identifiers:`로 제외한 뒤 나머지 documented internal function을 순서 없이 포함합니다. Minor utility나 platform-specific detail도 들어갈 수 있습니다.

====

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

Style과 DRM client usage stats

drm/i915 codebase는 kernel coding style에 더해 자체 style rule을 가지며 일부는 공통 style과 다릅니다. `i915_reg.h` register macro definition style guide가 register macro 작성 규칙을 설명합니다.

i915는 `drm-client-usage-stats`에 정의된 DRM client usage statistics specification을 구현합니다.

예시는 일반 fdinfo field인 `pos`, `flags`, `mnt_id`와 표준 `drm-driver`, `drm-pdev`, `drm-client-id`를 먼저 출력하고 engine별 busy time과 capacity를 나열합니다.

i915에서 가능한 `drm-engine-` key 이름은 `render`, `copy`, `video`, `video-enhance`입니다. Video engine group의 capacity가 2인 예처럼 동일 engine 여러 개를 하나의 key로 표현할 수 있습니다.

      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

=====

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`.