[PATCH 0/3] drm/i915: reorganize display documentation

[PATCH 0/3] drm/i915: reorganize display documentation

[Jani Nikula]

Move Intel display documentation under Documentation/gpu/intel-display,
and reorganize into smaller documents. There's lots of room for
improvement, but it's a start.

I intend to merge this through drm-intel-next, as it's fairly isolated.

BR,
Jani.

Jani Nikula (3):
  Documentation/gpu: add dedicated documentation for Intel display
  Documentation/gpu: use === for Intel display section heading
    underlines
  Documentation/gpu: add remaining DOC: comments to Intel display
    documentation

 Documentation/gpu/drivers.rst                 |   1 +
 Documentation/gpu/drm-kms.rst                 |   3 +
 Documentation/gpu/i915.rst                    | 202 +-----------------
 .../gpu/intel-display/async-flip.rst          |   8 +
 Documentation/gpu/intel-display/atomic.rst    |  11 +
 Documentation/gpu/intel-display/audio.rst     |  23 ++
 Documentation/gpu/intel-display/casf.rst      |   8 +
 Documentation/gpu/intel-display/cdclk.rst     |  11 +
 Documentation/gpu/intel-display/cmtg.rst      |   8 +
 Documentation/gpu/intel-display/dmc.rst       |  26 +++
 Documentation/gpu/intel-display/dpio.rst      |   8 +
 Documentation/gpu/intel-display/dpll.rst      |  14 ++
 Documentation/gpu/intel-display/drrs.rst      |  11 +
 Documentation/gpu/intel-display/dsb.rst       |  11 +
 Documentation/gpu/intel-display/fbc.rst       |  11 +
 .../gpu/intel-display/fifo-underrun.rst       |  11 +
 .../gpu/intel-display/frontbuffer.rst         |  14 ++
 Documentation/gpu/intel-display/hotplug.rst   |  11 +
 Documentation/gpu/intel-display/index.rst     |  44 ++++
 Documentation/gpu/intel-display/plane.rst     |  11 +
 Documentation/gpu/intel-display/psr.rst       |  11 +
 Documentation/gpu/intel-display/snps-phy.rst  |   8 +
 Documentation/gpu/intel-display/vbt.rst       |  14 ++
 Documentation/gpu/xe/index.rst                |   5 +
 24 files changed, 290 insertions(+), 195 deletions(-)
 create mode 100644 Documentation/gpu/intel-display/async-flip.rst
 create mode 100644 Documentation/gpu/intel-display/atomic.rst
 create mode 100644 Documentation/gpu/intel-display/audio.rst
 create mode 100644 Documentation/gpu/intel-display/casf.rst
 create mode 100644 Documentation/gpu/intel-display/cdclk.rst
 create mode 100644 Documentation/gpu/intel-display/cmtg.rst
 create mode 100644 Documentation/gpu/intel-display/dmc.rst
 create mode 100644 Documentation/gpu/intel-display/dpio.rst
 create mode 100644 Documentation/gpu/intel-display/dpll.rst
 create mode 100644 Documentation/gpu/intel-display/drrs.rst
 create mode 100644 Documentation/gpu/intel-display/dsb.rst
 create mode 100644 Documentation/gpu/intel-display/fbc.rst
 create mode 100644 Documentation/gpu/intel-display/fifo-underrun.rst
 create mode 100644 Documentation/gpu/intel-display/frontbuffer.rst
 create mode 100644 Documentation/gpu/intel-display/hotplug.rst
 create mode 100644 Documentation/gpu/intel-display/index.rst
 create mode 100644 Documentation/gpu/intel-display/plane.rst
 create mode 100644 Documentation/gpu/intel-display/psr.rst
 create mode 100644 Documentation/gpu/intel-display/snps-phy.rst
 create mode 100644 Documentation/gpu/intel-display/vbt.rst

-- 
2.47.3

[PATCH 1/3] Documentation/gpu: add dedicated documentation for Intel display

[Jani Nikula]

Nowadays, the display support for drm/i915 and drm/xe is shared between
the drivers, even though the code is located under drm/i915/display.

The drm/i915 documentation has everything, including display topics, in
one huge page, while the drm/xe documentation is well-organized but
hardly mentions display. It's not great, to put it mildly.

Split out the Intel display documentation to a dedicated directory,
Documentation/gpu/intel-display. Also directly split the
functionality/feature documentation to dedicated pages to keep the main
index page high level and readable. We'll want to organize this further,
but just sort them alphabetically for starters.

Drop the boilerplate documentation sections that don't actually document
anything.

Cross-reference drm/i915, drm/xe, and intel-display.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

---

Tip: 'git show --color-moved' conveniently highlights what gets moved
and what gets deleted.
---
 Documentation/gpu/drivers.rst                 |   1 +
 Documentation/gpu/drm-kms.rst                 |   3 +
 Documentation/gpu/i915.rst                    | 202 +-----------------
 .../gpu/intel-display/async-flip.rst          |   8 +
 Documentation/gpu/intel-display/audio.rst     |  23 ++
 Documentation/gpu/intel-display/cdclk.rst     |  11 +
 Documentation/gpu/intel-display/dmc.rst       |  26 +++
 Documentation/gpu/intel-display/dpio.rst      |   8 +
 Documentation/gpu/intel-display/dpll.rst      |  14 ++
 Documentation/gpu/intel-display/drrs.rst      |  11 +
 Documentation/gpu/intel-display/dsb.rst       |  11 +
 Documentation/gpu/intel-display/fbc.rst       |  11 +
 .../gpu/intel-display/fifo-underrun.rst       |  11 +
 .../gpu/intel-display/frontbuffer.rst         |  14 ++
 Documentation/gpu/intel-display/hotplug.rst   |  11 +
 Documentation/gpu/intel-display/index.rst     |  40 ++++
 Documentation/gpu/intel-display/plane.rst     |  11 +
 Documentation/gpu/intel-display/psr.rst       |  11 +
 Documentation/gpu/intel-display/vbt.rst       |  14 ++
 Documentation/gpu/xe/index.rst                |   5 +
 20 files changed, 251 insertions(+), 195 deletions(-)
 create mode 100644 Documentation/gpu/intel-display/async-flip.rst
 create mode 100644 Documentation/gpu/intel-display/audio.rst
 create mode 100644 Documentation/gpu/intel-display/cdclk.rst
 create mode 100644 Documentation/gpu/intel-display/dmc.rst
 create mode 100644 Documentation/gpu/intel-display/dpio.rst
 create mode 100644 Documentation/gpu/intel-display/dpll.rst
 create mode 100644 Documentation/gpu/intel-display/drrs.rst
 create mode 100644 Documentation/gpu/intel-display/dsb.rst
 create mode 100644 Documentation/gpu/intel-display/fbc.rst
 create mode 100644 Documentation/gpu/intel-display/fifo-underrun.rst
 create mode 100644 Documentation/gpu/intel-display/frontbuffer.rst
 create mode 100644 Documentation/gpu/intel-display/hotplug.rst
 create mode 100644 Documentation/gpu/intel-display/index.rst
 create mode 100644 Documentation/gpu/intel-display/plane.rst
 create mode 100644 Documentation/gpu/intel-display/psr.rst
 create mode 100644 Documentation/gpu/intel-display/vbt.rst

diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 2e13e0ad7e88..20d2c454aa1d 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -8,6 +8,7 @@ GPU Driver Documentation
    amdgpu/index
    i915
    imagination/index
+   intel-display/index
    mcde
    meson
    nouveau
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index fbe0583eb84c..a125052f46bc 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -1,3 +1,6 @@
+
+.. _drm-kms:
+
 =========================
 Kernel Mode Setting (KMS)
 =========================
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index eba09c3ddce4..0c9d68758533 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -1,3 +1,6 @@
+
+.. _drm/i915:
+
 ===========================
  drm/i915 Intel GFX Driver
 ===========================
@@ -7,6 +10,9 @@ 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
 ==========================
 
@@ -64,200 +70,6 @@ Workarounds
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
    :doc: Hardware workarounds
 
-Display Hardware Handling
-=========================
-
-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
 ==============
 
@@ -568,7 +380,7 @@ The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_
 
 DMC
 ---
-See `DMC Firmware Support`_
+See :ref:`drm/intel-display/dmc`.
 
 Tracing
 =======
diff --git a/Documentation/gpu/intel-display/async-flip.rst b/Documentation/gpu/intel-display/async-flip.rst
new file mode 100644
index 000000000000..e4ae4012efc5
--- /dev/null
+++ b/Documentation/gpu/intel-display/async-flip.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Asynchronous Page Flip
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
+   :doc: asynchronous flip implementation
diff --git a/Documentation/gpu/intel-display/audio.rst b/Documentation/gpu/intel-display/audio.rst
new file mode 100644
index 000000000000..7d3c1b514b0e
--- /dev/null
+++ b/Documentation/gpu/intel-display/audio.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/cdclk.rst b/Documentation/gpu/intel-display/cdclk.rst
new file mode 100644
index 000000000000..231b22a733e7
--- /dev/null
+++ b/Documentation/gpu/intel-display/cdclk.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/dmc.rst b/Documentation/gpu/intel-display/dmc.rst
new file mode 100644
index 000000000000..2fcdbd457d79
--- /dev/null
+++ b/Documentation/gpu/intel-display/dmc.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+.. _drm/intel-display/dmc:
+
+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
diff --git a/Documentation/gpu/intel-display/dpio.rst b/Documentation/gpu/intel-display/dpio.rst
new file mode 100644
index 000000000000..32e6f299f256
--- /dev/null
+++ b/Documentation/gpu/intel-display/dpio.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+DPIO
+----
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
+   :doc: DPIO
diff --git a/Documentation/gpu/intel-display/dpll.rst b/Documentation/gpu/intel-display/dpll.rst
new file mode 100644
index 000000000000..35e8168ccfb9
--- /dev/null
+++ b/Documentation/gpu/intel-display/dpll.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/drrs.rst b/Documentation/gpu/intel-display/drrs.rst
new file mode 100644
index 000000000000..adb413f300f1
--- /dev/null
+++ b/Documentation/gpu/intel-display/drrs.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/dsb.rst b/Documentation/gpu/intel-display/dsb.rst
new file mode 100644
index 000000000000..cbd40b0a4e7b
--- /dev/null
+++ b/Documentation/gpu/intel-display/dsb.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/fbc.rst b/Documentation/gpu/intel-display/fbc.rst
new file mode 100644
index 000000000000..40f9d16bdebd
--- /dev/null
+++ b/Documentation/gpu/intel-display/fbc.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/fifo-underrun.rst b/Documentation/gpu/intel-display/fifo-underrun.rst
new file mode 100644
index 000000000000..50731f3a1f03
--- /dev/null
+++ b/Documentation/gpu/intel-display/fifo-underrun.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/frontbuffer.rst b/Documentation/gpu/intel-display/frontbuffer.rst
new file mode 100644
index 000000000000..2a1bc63ba6b4
--- /dev/null
+++ b/Documentation/gpu/intel-display/frontbuffer.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/hotplug.rst b/Documentation/gpu/intel-display/hotplug.rst
new file mode 100644
index 000000000000..4cd9dd5ac8fc
--- /dev/null
+++ b/Documentation/gpu/intel-display/hotplug.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Hotplug
+-------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
+   :doc: Hotplug
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
+   :internal:
diff --git a/Documentation/gpu/intel-display/index.rst b/Documentation/gpu/intel-display/index.rst
new file mode 100644
index 000000000000..8d40363b8f90
--- /dev/null
+++ b/Documentation/gpu/intel-display/index.rst
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+.. _drm/intel-display:
+
+====================
+Intel Display Driver
+====================
+
+The Intel display driver provides the display, or :ref:`drm-kms`, support for
+both the :ref:`drm/xe <drm/xe>` and :ref:`drm/i915 <drm/i915>` Intel GPU
+drivers.
+
+The source code currently resides under ``drivers/gpu/drm/i915/display`` due to
+historical reasons, and it's compiled separately into both drm/xe and drm/i915
+kernel modules.
+
+The drm/xe and drm/i915 drivers are the "core" or "parent" drivers for display,
+as they initialize and own the drm device, and pass that on to the display
+driver. The display driver isn't an independent driver in that sense.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Detailed display topics
+
+   async-flip
+   audio
+   cdclk
+   dmc
+   dpio
+   dpll
+   drrs
+   dsb
+   fbc
+   fifo-underrun
+   frontbuffer
+   hotplug
+   plane
+   psr
+   vbt
diff --git a/Documentation/gpu/intel-display/plane.rst b/Documentation/gpu/intel-display/plane.rst
new file mode 100644
index 000000000000..41cf6571aab0
--- /dev/null
+++ b/Documentation/gpu/intel-display/plane.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/psr.rst b/Documentation/gpu/intel-display/psr.rst
new file mode 100644
index 000000000000..134c905f500e
--- /dev/null
+++ b/Documentation/gpu/intel-display/psr.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/intel-display/vbt.rst b/Documentation/gpu/intel-display/vbt.rst
new file mode 100644
index 000000000000..bbc7ee183f1b
--- /dev/null
+++ b/Documentation/gpu/intel-display/vbt.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+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:
diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
index 874ffcb6da3a..665c0e93601c 100644
--- a/Documentation/gpu/xe/index.rst
+++ b/Documentation/gpu/xe/index.rst
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
 
+.. _drm/xe:
+
 =======================
 drm/xe Intel GFX Driver
 =======================
@@ -8,6 +10,9 @@ The drm/xe driver supports some future GFX cards with rendering, display,
 compute and media. Support for currently available platforms like TGL, ADL,
 DG2, etc is provided to prototype the driver.
 
+The display, or :ref:`drm-kms`, support for drm/xe is provided by
+:ref:`drm/intel-display`, and shared with :ref:`drm/i915 <drm/i915>`.
+
 .. toctree::
    :titlesonly:
 
-- 
2.47.3

[PATCH 2/3] Documentation/gpu: use === for Intel display section heading underlines

[Jani Nikula]

Prefer to use === instead of --- for top level section heading
underlines to allow using the latter for sub-headings later.

While at it, fix the underline lenghts where needed.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/gpu/intel-display/async-flip.rst    | 2 +-
 Documentation/gpu/intel-display/audio.rst         | 4 ++--
 Documentation/gpu/intel-display/cdclk.rst         | 2 +-
 Documentation/gpu/intel-display/dmc.rst           | 6 +++---
 Documentation/gpu/intel-display/dpio.rst          | 2 +-
 Documentation/gpu/intel-display/dpll.rst          | 2 +-
 Documentation/gpu/intel-display/drrs.rst          | 2 +-
 Documentation/gpu/intel-display/dsb.rst           | 2 +-
 Documentation/gpu/intel-display/fbc.rst           | 2 +-
 Documentation/gpu/intel-display/fifo-underrun.rst | 2 +-
 Documentation/gpu/intel-display/frontbuffer.rst   | 2 +-
 Documentation/gpu/intel-display/hotplug.rst       | 2 +-
 Documentation/gpu/intel-display/plane.rst         | 2 +-
 Documentation/gpu/intel-display/psr.rst           | 2 +-
 Documentation/gpu/intel-display/vbt.rst           | 2 +-
 15 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/Documentation/gpu/intel-display/async-flip.rst b/Documentation/gpu/intel-display/async-flip.rst
index e4ae4012efc5..40f93e885bb7 100644
--- a/Documentation/gpu/intel-display/async-flip.rst
+++ b/Documentation/gpu/intel-display/async-flip.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Asynchronous Page Flip
-----------------------
+======================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
    :doc: asynchronous flip implementation
diff --git a/Documentation/gpu/intel-display/audio.rst b/Documentation/gpu/intel-display/audio.rst
index 7d3c1b514b0e..eef95df75f8d 100644
--- a/Documentation/gpu/intel-display/audio.rst
+++ b/Documentation/gpu/intel-display/audio.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 High Definition Audio
----------------------
+=====================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
    :doc: High Definition Audio over HDMI and Display Port
@@ -14,7 +14,7 @@ High Definition Audio
    :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
diff --git a/Documentation/gpu/intel-display/cdclk.rst b/Documentation/gpu/intel-display/cdclk.rst
index 231b22a733e7..a66d623b0ec9 100644
--- a/Documentation/gpu/intel-display/cdclk.rst
+++ b/Documentation/gpu/intel-display/cdclk.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Display clocks
---------------
+==============
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
    :doc: CDCLK / RAWCLK
diff --git a/Documentation/gpu/intel-display/dmc.rst b/Documentation/gpu/intel-display/dmc.rst
index 2fcdbd457d79..4368da4c7048 100644
--- a/Documentation/gpu/intel-display/dmc.rst
+++ b/Documentation/gpu/intel-display/dmc.rst
@@ -4,7 +4,7 @@
 .. _drm/intel-display/dmc:
 
 DMC Firmware Support
---------------------
+====================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
    :doc: DMC Firmware Support
@@ -14,13 +14,13 @@ DMC Firmware Support
 
 
 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
diff --git a/Documentation/gpu/intel-display/dpio.rst b/Documentation/gpu/intel-display/dpio.rst
index 32e6f299f256..84d92ac162f8 100644
--- a/Documentation/gpu/intel-display/dpio.rst
+++ b/Documentation/gpu/intel-display/dpio.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 DPIO
-----
+====
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
    :doc: DPIO
diff --git a/Documentation/gpu/intel-display/dpll.rst b/Documentation/gpu/intel-display/dpll.rst
index 35e8168ccfb9..c750352e0ae5 100644
--- a/Documentation/gpu/intel-display/dpll.rst
+++ b/Documentation/gpu/intel-display/dpll.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Display PLLs
-------------
+============
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
    :doc: Display PLLs
diff --git a/Documentation/gpu/intel-display/drrs.rst b/Documentation/gpu/intel-display/drrs.rst
index adb413f300f1..a5aaba63d6b9 100644
--- a/Documentation/gpu/intel-display/drrs.rst
+++ b/Documentation/gpu/intel-display/drrs.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Display Refresh Rate Switching (DRRS)
--------------------------------------
+=====================================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
    :doc: Display Refresh Rate Switching (DRRS)
diff --git a/Documentation/gpu/intel-display/dsb.rst b/Documentation/gpu/intel-display/dsb.rst
index cbd40b0a4e7b..857aca59995a 100644
--- a/Documentation/gpu/intel-display/dsb.rst
+++ b/Documentation/gpu/intel-display/dsb.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Display State Buffer
---------------------
+====================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
    :doc: DSB
diff --git a/Documentation/gpu/intel-display/fbc.rst b/Documentation/gpu/intel-display/fbc.rst
index 40f9d16bdebd..de9e19021f50 100644
--- a/Documentation/gpu/intel-display/fbc.rst
+++ b/Documentation/gpu/intel-display/fbc.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Frame Buffer Compression (FBC)
-------------------------------
+==============================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
    :doc: Frame Buffer Compression (FBC)
diff --git a/Documentation/gpu/intel-display/fifo-underrun.rst b/Documentation/gpu/intel-display/fifo-underrun.rst
index 50731f3a1f03..5d8f01921506 100644
--- a/Documentation/gpu/intel-display/fifo-underrun.rst
+++ b/Documentation/gpu/intel-display/fifo-underrun.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Display FIFO Underrun Reporting
--------------------------------
+===============================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
    :doc: fifo underrun handling
diff --git a/Documentation/gpu/intel-display/frontbuffer.rst b/Documentation/gpu/intel-display/frontbuffer.rst
index 2a1bc63ba6b4..7ae38e0827bf 100644
--- a/Documentation/gpu/intel-display/frontbuffer.rst
+++ b/Documentation/gpu/intel-display/frontbuffer.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Frontbuffer Tracking
---------------------
+====================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
    :doc: frontbuffer tracking
diff --git a/Documentation/gpu/intel-display/hotplug.rst b/Documentation/gpu/intel-display/hotplug.rst
index 4cd9dd5ac8fc..f33bc0087c27 100644
--- a/Documentation/gpu/intel-display/hotplug.rst
+++ b/Documentation/gpu/intel-display/hotplug.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Hotplug
--------
+=======
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
    :doc: Hotplug
diff --git a/Documentation/gpu/intel-display/plane.rst b/Documentation/gpu/intel-display/plane.rst
index 41cf6571aab0..59932a82051b 100644
--- a/Documentation/gpu/intel-display/plane.rst
+++ b/Documentation/gpu/intel-display/plane.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Atomic Plane Helpers
---------------------
+====================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_plane.c
    :doc: atomic plane helpers
diff --git a/Documentation/gpu/intel-display/psr.rst b/Documentation/gpu/intel-display/psr.rst
index 134c905f500e..63e56abcdd56 100644
--- a/Documentation/gpu/intel-display/psr.rst
+++ b/Documentation/gpu/intel-display/psr.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Panel Self Refresh PSR (PSR/SRD)
---------------------------------
+================================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
    :doc: Panel Self Refresh (PSR/SRD)
diff --git a/Documentation/gpu/intel-display/vbt.rst b/Documentation/gpu/intel-display/vbt.rst
index bbc7ee183f1b..be69f7fd7b39 100644
--- a/Documentation/gpu/intel-display/vbt.rst
+++ b/Documentation/gpu/intel-display/vbt.rst
@@ -2,7 +2,7 @@
 .. Copyright © 2026 Intel Corporation
 
 Video BIOS Table (VBT)
-----------------------
+======================
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
    :doc: Video BIOS Table (VBT)
-- 
2.47.3

[PATCH 3/3] Documentation/gpu: add remaining DOC: comments to Intel display documentation

[Jani Nikula]

Not all of the overview DOC: comments in the display driver are
incorporated into the documentation. Add the missing ones, including
some function documentation.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/gpu/intel-display/atomic.rst   | 11 +++++++++++
 Documentation/gpu/intel-display/casf.rst     |  8 ++++++++
 Documentation/gpu/intel-display/cmtg.rst     |  8 ++++++++
 Documentation/gpu/intel-display/index.rst    |  4 ++++
 Documentation/gpu/intel-display/snps-phy.rst |  8 ++++++++
 5 files changed, 39 insertions(+)
 create mode 100644 Documentation/gpu/intel-display/atomic.rst
 create mode 100644 Documentation/gpu/intel-display/casf.rst
 create mode 100644 Documentation/gpu/intel-display/cmtg.rst
 create mode 100644 Documentation/gpu/intel-display/snps-phy.rst

diff --git a/Documentation/gpu/intel-display/atomic.rst b/Documentation/gpu/intel-display/atomic.rst
new file mode 100644
index 000000000000..43a473181e7a
--- /dev/null
+++ b/Documentation/gpu/intel-display/atomic.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Atomic Modeset Support
+======================
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
+   :doc: atomic modeset support
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
+   :internal:
diff --git a/Documentation/gpu/intel-display/casf.rst b/Documentation/gpu/intel-display/casf.rst
new file mode 100644
index 000000000000..406778ccd94c
--- /dev/null
+++ b/Documentation/gpu/intel-display/casf.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Content Adaptive Sharpness Filter (CASF)
+========================================
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_casf.c
+   :doc: Content Adaptive Sharpness Filter (CASF)
diff --git a/Documentation/gpu/intel-display/cmtg.rst b/Documentation/gpu/intel-display/cmtg.rst
new file mode 100644
index 000000000000..04edd0bd165d
--- /dev/null
+++ b/Documentation/gpu/intel-display/cmtg.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Common Primary Timing Generator (CMTG)
+======================================
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cmtg.c
+   :doc: Common Primary Timing Generator (CMTG)
diff --git a/Documentation/gpu/intel-display/index.rst b/Documentation/gpu/intel-display/index.rst
index 8d40363b8f90..01c3d1e576b7 100644
--- a/Documentation/gpu/intel-display/index.rst
+++ b/Documentation/gpu/intel-display/index.rst
@@ -24,8 +24,11 @@ driver. The display driver isn't an independent driver in that sense.
    :caption: Detailed display topics
 
    async-flip
+   atomic
    audio
+   casf
    cdclk
+   cmtg
    dmc
    dpio
    dpll
@@ -37,4 +40,5 @@ driver. The display driver isn't an independent driver in that sense.
    hotplug
    plane
    psr
+   snps-phy
    vbt
diff --git a/Documentation/gpu/intel-display/snps-phy.rst b/Documentation/gpu/intel-display/snps-phy.rst
new file mode 100644
index 000000000000..c9e333fa7f62
--- /dev/null
+++ b/Documentation/gpu/intel-display/snps-phy.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT
+.. Copyright © 2026 Intel Corporation
+
+Synopsis PHY support
+====================
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_snps_phy.c
+   :doc: Synopsis PHY support
-- 
2.47.3

Re: [PATCH 1/3] Documentation/gpu: add dedicated documentation for Intel display

[Rodrigo Vivi]

On Fri, May 08, 2026 at 01:20:47PM +0300, Jani Nikula wrote:
> Nowadays, the display support for drm/i915 and drm/xe is shared between
> the drivers, even though the code is located under drm/i915/display.
> 
> The drm/i915 documentation has everything, including display topics, in
> one huge page, while the drm/xe documentation is well-organized but
> hardly mentions display. It's not great, to put it mildly.
> 
> Split out the Intel display documentation to a dedicated directory,
> Documentation/gpu/intel-display. Also directly split the
> functionality/feature documentation to dedicated pages to keep the main
> index page high level and readable. We'll want to organize this further,
> but just sort them alphabetically for starters.
> 
> Drop the boilerplate documentation sections that don't actually document
> anything.
> 
> Cross-reference drm/i915, drm/xe, and intel-display.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> 
> ---
> 
> Tip: 'git show --color-moved' conveniently highlights what gets moved
> and what gets deleted.
> ---
>  Documentation/gpu/drivers.rst                 |   1 +
>  Documentation/gpu/drm-kms.rst                 |   3 +
>  Documentation/gpu/i915.rst                    | 202 +-----------------
>  .../gpu/intel-display/async-flip.rst          |   8 +
>  Documentation/gpu/intel-display/audio.rst     |  23 ++
>  Documentation/gpu/intel-display/cdclk.rst     |  11 +
>  Documentation/gpu/intel-display/dmc.rst       |  26 +++
>  Documentation/gpu/intel-display/dpio.rst      |   8 +
>  Documentation/gpu/intel-display/dpll.rst      |  14 ++
>  Documentation/gpu/intel-display/drrs.rst      |  11 +
>  Documentation/gpu/intel-display/dsb.rst       |  11 +
>  Documentation/gpu/intel-display/fbc.rst       |  11 +
>  .../gpu/intel-display/fifo-underrun.rst       |  11 +
>  .../gpu/intel-display/frontbuffer.rst         |  14 ++
>  Documentation/gpu/intel-display/hotplug.rst   |  11 +
>  Documentation/gpu/intel-display/index.rst     |  40 ++++
>  Documentation/gpu/intel-display/plane.rst     |  11 +
>  Documentation/gpu/intel-display/psr.rst       |  11 +
>  Documentation/gpu/intel-display/vbt.rst       |  14 ++
>  Documentation/gpu/xe/index.rst                |   5 +
>  20 files changed, 251 insertions(+), 195 deletions(-)
>  create mode 100644 Documentation/gpu/intel-display/async-flip.rst
>  create mode 100644 Documentation/gpu/intel-display/audio.rst
>  create mode 100644 Documentation/gpu/intel-display/cdclk.rst
>  create mode 100644 Documentation/gpu/intel-display/dmc.rst
>  create mode 100644 Documentation/gpu/intel-display/dpio.rst
>  create mode 100644 Documentation/gpu/intel-display/dpll.rst
>  create mode 100644 Documentation/gpu/intel-display/drrs.rst
>  create mode 100644 Documentation/gpu/intel-display/dsb.rst
>  create mode 100644 Documentation/gpu/intel-display/fbc.rst
>  create mode 100644 Documentation/gpu/intel-display/fifo-underrun.rst
>  create mode 100644 Documentation/gpu/intel-display/frontbuffer.rst
>  create mode 100644 Documentation/gpu/intel-display/hotplug.rst
>  create mode 100644 Documentation/gpu/intel-display/index.rst
>  create mode 100644 Documentation/gpu/intel-display/plane.rst
>  create mode 100644 Documentation/gpu/intel-display/psr.rst
>  create mode 100644 Documentation/gpu/intel-display/vbt.rst
> 
> diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
> index 2e13e0ad7e88..20d2c454aa1d 100644
> --- a/Documentation/gpu/drivers.rst
> +++ b/Documentation/gpu/drivers.rst
> @@ -8,6 +8,7 @@ GPU Driver Documentation
>     amdgpu/index
>     i915
>     imagination/index
> +   intel-display/index
>     mcde
>     meson
>     nouveau
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index fbe0583eb84c..a125052f46bc 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -1,3 +1,6 @@
> +
> +.. _drm-kms:
> +
>  =========================
>  Kernel Mode Setting (KMS)
>  =========================
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index eba09c3ddce4..0c9d68758533 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -1,3 +1,6 @@
> +
> +.. _drm/i915:
> +
>  ===========================
>   drm/i915 Intel GFX Driver
>  ===========================
> @@ -7,6 +10,9 @@ 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
>  ==========================
>  
> @@ -64,200 +70,6 @@ Workarounds
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
>     :doc: Hardware workarounds
>  
> -Display Hardware Handling
> -=========================
> -
> -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
>  ==============
>  
> @@ -568,7 +380,7 @@ The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_
>  
>  DMC
>  ---
> -See `DMC Firmware Support`_
> +See :ref:`drm/intel-display/dmc`.
>  
>  Tracing
>  =======
> diff --git a/Documentation/gpu/intel-display/async-flip.rst b/Documentation/gpu/intel-display/async-flip.rst
> new file mode 100644
> index 000000000000..e4ae4012efc5
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/async-flip.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Asynchronous Page Flip
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
> +   :doc: asynchronous flip implementation
> diff --git a/Documentation/gpu/intel-display/audio.rst b/Documentation/gpu/intel-display/audio.rst
> new file mode 100644
> index 000000000000..7d3c1b514b0e
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/audio.rst
> @@ -0,0 +1,23 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/cdclk.rst b/Documentation/gpu/intel-display/cdclk.rst
> new file mode 100644
> index 000000000000..231b22a733e7
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/cdclk.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/dmc.rst b/Documentation/gpu/intel-display/dmc.rst
> new file mode 100644
> index 000000000000..2fcdbd457d79
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/dmc.rst
> @@ -0,0 +1,26 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +.. _drm/intel-display/dmc:
> +
> +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
> diff --git a/Documentation/gpu/intel-display/dpio.rst b/Documentation/gpu/intel-display/dpio.rst
> new file mode 100644
> index 000000000000..32e6f299f256
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/dpio.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +DPIO
> +----
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
> +   :doc: DPIO
> diff --git a/Documentation/gpu/intel-display/dpll.rst b/Documentation/gpu/intel-display/dpll.rst
> new file mode 100644
> index 000000000000..35e8168ccfb9
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/dpll.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/drrs.rst b/Documentation/gpu/intel-display/drrs.rst
> new file mode 100644
> index 000000000000..adb413f300f1
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/drrs.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/dsb.rst b/Documentation/gpu/intel-display/dsb.rst
> new file mode 100644
> index 000000000000..cbd40b0a4e7b
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/dsb.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/fbc.rst b/Documentation/gpu/intel-display/fbc.rst
> new file mode 100644
> index 000000000000..40f9d16bdebd
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/fbc.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/fifo-underrun.rst b/Documentation/gpu/intel-display/fifo-underrun.rst
> new file mode 100644
> index 000000000000..50731f3a1f03
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/fifo-underrun.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/frontbuffer.rst b/Documentation/gpu/intel-display/frontbuffer.rst
> new file mode 100644
> index 000000000000..2a1bc63ba6b4
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/frontbuffer.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/hotplug.rst b/Documentation/gpu/intel-display/hotplug.rst
> new file mode 100644
> index 000000000000..4cd9dd5ac8fc
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/hotplug.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Hotplug
> +-------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
> +   :doc: Hotplug
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
> +   :internal:
> diff --git a/Documentation/gpu/intel-display/index.rst b/Documentation/gpu/intel-display/index.rst
> new file mode 100644
> index 000000000000..8d40363b8f90
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/index.rst
> @@ -0,0 +1,40 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +.. _drm/intel-display:
> +
> +====================
> +Intel Display Driver
> +====================
> +
> +The Intel display driver provides the display, or :ref:`drm-kms`, support for
> +both the :ref:`drm/xe <drm/xe>` and :ref:`drm/i915 <drm/i915>` Intel GPU
> +drivers.
> +
> +The source code currently resides under ``drivers/gpu/drm/i915/display`` due to
> +historical reasons, and it's compiled separately into both drm/xe and drm/i915
> +kernel modules.
> +
> +The drm/xe and drm/i915 drivers are the "core" or "parent" drivers for display,
> +as they initialize and own the drm device, and pass that on to the display
> +driver. The display driver isn't an independent driver in that sense.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   :caption: Detailed display topics
> +
> +   async-flip
> +   audio
> +   cdclk
> +   dmc
> +   dpio
> +   dpll
> +   drrs
> +   dsb
> +   fbc
> +   fifo-underrun
> +   frontbuffer
> +   hotplug
> +   plane
> +   psr
> +   vbt
> diff --git a/Documentation/gpu/intel-display/plane.rst b/Documentation/gpu/intel-display/plane.rst
> new file mode 100644
> index 000000000000..41cf6571aab0
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/plane.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/psr.rst b/Documentation/gpu/intel-display/psr.rst
> new file mode 100644
> index 000000000000..134c905f500e
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/psr.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/intel-display/vbt.rst b/Documentation/gpu/intel-display/vbt.rst
> new file mode 100644
> index 000000000000..bbc7ee183f1b
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/vbt.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +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:
> diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
> index 874ffcb6da3a..665c0e93601c 100644
> --- a/Documentation/gpu/xe/index.rst
> +++ b/Documentation/gpu/xe/index.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
>  
> +.. _drm/xe:
> +
>  =======================
>  drm/xe Intel GFX Driver
>  =======================
> @@ -8,6 +10,9 @@ The drm/xe driver supports some future GFX cards with rendering, display,
>  compute and media. Support for currently available platforms like TGL, ADL,
>  DG2, etc is provided to prototype the driver.
>  
> +The display, or :ref:`drm-kms`, support for drm/xe is provided by
> +:ref:`drm/intel-display`, and shared with :ref:`drm/i915 <drm/i915>`.

Great idea!

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> +
>  .. toctree::
>     :titlesonly:
>  
> -- 
> 2.47.3
> 

Re: [PATCH 2/3] Documentation/gpu: use === for Intel display section heading underlines

[Rodrigo Vivi]

On Fri, May 08, 2026 at 01:20:48PM +0300, Jani Nikula wrote:
> Prefer to use === instead of --- for top level section heading
> underlines to allow using the latter for sub-headings later.
> 
> While at it, fix the underline lenghts where needed.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> ---
>  Documentation/gpu/intel-display/async-flip.rst    | 2 +-
>  Documentation/gpu/intel-display/audio.rst         | 4 ++--
>  Documentation/gpu/intel-display/cdclk.rst         | 2 +-
>  Documentation/gpu/intel-display/dmc.rst           | 6 +++---
>  Documentation/gpu/intel-display/dpio.rst          | 2 +-
>  Documentation/gpu/intel-display/dpll.rst          | 2 +-
>  Documentation/gpu/intel-display/drrs.rst          | 2 +-
>  Documentation/gpu/intel-display/dsb.rst           | 2 +-
>  Documentation/gpu/intel-display/fbc.rst           | 2 +-
>  Documentation/gpu/intel-display/fifo-underrun.rst | 2 +-
>  Documentation/gpu/intel-display/frontbuffer.rst   | 2 +-
>  Documentation/gpu/intel-display/hotplug.rst       | 2 +-
>  Documentation/gpu/intel-display/plane.rst         | 2 +-
>  Documentation/gpu/intel-display/psr.rst           | 2 +-
>  Documentation/gpu/intel-display/vbt.rst           | 2 +-
>  15 files changed, 18 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/gpu/intel-display/async-flip.rst b/Documentation/gpu/intel-display/async-flip.rst
> index e4ae4012efc5..40f93e885bb7 100644
> --- a/Documentation/gpu/intel-display/async-flip.rst
> +++ b/Documentation/gpu/intel-display/async-flip.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Asynchronous Page Flip
> -----------------------
> +======================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_display.c
>     :doc: asynchronous flip implementation
> diff --git a/Documentation/gpu/intel-display/audio.rst b/Documentation/gpu/intel-display/audio.rst
> index 7d3c1b514b0e..eef95df75f8d 100644
> --- a/Documentation/gpu/intel-display/audio.rst
> +++ b/Documentation/gpu/intel-display/audio.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  High Definition Audio
> ----------------------
> +=====================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c
>     :doc: High Definition Audio over HDMI and Display Port
> @@ -14,7 +14,7 @@ High Definition Audio
>     :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
> diff --git a/Documentation/gpu/intel-display/cdclk.rst b/Documentation/gpu/intel-display/cdclk.rst
> index 231b22a733e7..a66d623b0ec9 100644
> --- a/Documentation/gpu/intel-display/cdclk.rst
> +++ b/Documentation/gpu/intel-display/cdclk.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Display clocks
> ---------------
> +==============
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c
>     :doc: CDCLK / RAWCLK
> diff --git a/Documentation/gpu/intel-display/dmc.rst b/Documentation/gpu/intel-display/dmc.rst
> index 2fcdbd457d79..4368da4c7048 100644
> --- a/Documentation/gpu/intel-display/dmc.rst
> +++ b/Documentation/gpu/intel-display/dmc.rst
> @@ -4,7 +4,7 @@
>  .. _drm/intel-display/dmc:
>  
>  DMC Firmware Support
> ---------------------
> +====================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dmc.c
>     :doc: DMC Firmware Support
> @@ -14,13 +14,13 @@ DMC Firmware Support
>  
>  
>  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
> diff --git a/Documentation/gpu/intel-display/dpio.rst b/Documentation/gpu/intel-display/dpio.rst
> index 32e6f299f256..84d92ac162f8 100644
> --- a/Documentation/gpu/intel-display/dpio.rst
> +++ b/Documentation/gpu/intel-display/dpio.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  DPIO
> -----
> +====
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c
>     :doc: DPIO
> diff --git a/Documentation/gpu/intel-display/dpll.rst b/Documentation/gpu/intel-display/dpll.rst
> index 35e8168ccfb9..c750352e0ae5 100644
> --- a/Documentation/gpu/intel-display/dpll.rst
> +++ b/Documentation/gpu/intel-display/dpll.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Display PLLs
> -------------
> +============
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c
>     :doc: Display PLLs
> diff --git a/Documentation/gpu/intel-display/drrs.rst b/Documentation/gpu/intel-display/drrs.rst
> index adb413f300f1..a5aaba63d6b9 100644
> --- a/Documentation/gpu/intel-display/drrs.rst
> +++ b/Documentation/gpu/intel-display/drrs.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Display Refresh Rate Switching (DRRS)
> --------------------------------------
> +=====================================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c
>     :doc: Display Refresh Rate Switching (DRRS)
> diff --git a/Documentation/gpu/intel-display/dsb.rst b/Documentation/gpu/intel-display/dsb.rst
> index cbd40b0a4e7b..857aca59995a 100644
> --- a/Documentation/gpu/intel-display/dsb.rst
> +++ b/Documentation/gpu/intel-display/dsb.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Display State Buffer
> ---------------------
> +====================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
>     :doc: DSB
> diff --git a/Documentation/gpu/intel-display/fbc.rst b/Documentation/gpu/intel-display/fbc.rst
> index 40f9d16bdebd..de9e19021f50 100644
> --- a/Documentation/gpu/intel-display/fbc.rst
> +++ b/Documentation/gpu/intel-display/fbc.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Frame Buffer Compression (FBC)
> -------------------------------
> +==============================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c
>     :doc: Frame Buffer Compression (FBC)
> diff --git a/Documentation/gpu/intel-display/fifo-underrun.rst b/Documentation/gpu/intel-display/fifo-underrun.rst
> index 50731f3a1f03..5d8f01921506 100644
> --- a/Documentation/gpu/intel-display/fifo-underrun.rst
> +++ b/Documentation/gpu/intel-display/fifo-underrun.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Display FIFO Underrun Reporting
> --------------------------------
> +===============================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
>     :doc: fifo underrun handling
> diff --git a/Documentation/gpu/intel-display/frontbuffer.rst b/Documentation/gpu/intel-display/frontbuffer.rst
> index 2a1bc63ba6b4..7ae38e0827bf 100644
> --- a/Documentation/gpu/intel-display/frontbuffer.rst
> +++ b/Documentation/gpu/intel-display/frontbuffer.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Frontbuffer Tracking
> ---------------------
> +====================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c
>     :doc: frontbuffer tracking
> diff --git a/Documentation/gpu/intel-display/hotplug.rst b/Documentation/gpu/intel-display/hotplug.rst
> index 4cd9dd5ac8fc..f33bc0087c27 100644
> --- a/Documentation/gpu/intel-display/hotplug.rst
> +++ b/Documentation/gpu/intel-display/hotplug.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Hotplug
> --------
> +=======
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c
>     :doc: Hotplug
> diff --git a/Documentation/gpu/intel-display/plane.rst b/Documentation/gpu/intel-display/plane.rst
> index 41cf6571aab0..59932a82051b 100644
> --- a/Documentation/gpu/intel-display/plane.rst
> +++ b/Documentation/gpu/intel-display/plane.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Atomic Plane Helpers
> ---------------------
> +====================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_plane.c
>     :doc: atomic plane helpers
> diff --git a/Documentation/gpu/intel-display/psr.rst b/Documentation/gpu/intel-display/psr.rst
> index 134c905f500e..63e56abcdd56 100644
> --- a/Documentation/gpu/intel-display/psr.rst
> +++ b/Documentation/gpu/intel-display/psr.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Panel Self Refresh PSR (PSR/SRD)
> ---------------------------------
> +================================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c
>     :doc: Panel Self Refresh (PSR/SRD)
> diff --git a/Documentation/gpu/intel-display/vbt.rst b/Documentation/gpu/intel-display/vbt.rst
> index bbc7ee183f1b..be69f7fd7b39 100644
> --- a/Documentation/gpu/intel-display/vbt.rst
> +++ b/Documentation/gpu/intel-display/vbt.rst
> @@ -2,7 +2,7 @@
>  .. Copyright © 2026 Intel Corporation
>  
>  Video BIOS Table (VBT)
> -----------------------
> +======================
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c
>     :doc: Video BIOS Table (VBT)
> -- 
> 2.47.3
> 

Re: [PATCH 3/3] Documentation/gpu: add remaining DOC: comments to Intel display documentation

[Rodrigo Vivi]

On Fri, May 08, 2026 at 01:20:49PM +0300, Jani Nikula wrote:
> Not all of the overview DOC: comments in the display driver are
> incorporated into the documentation. Add the missing ones, including
> some function documentation.
> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  Documentation/gpu/intel-display/atomic.rst   | 11 +++++++++++
>  Documentation/gpu/intel-display/casf.rst     |  8 ++++++++
>  Documentation/gpu/intel-display/cmtg.rst     |  8 ++++++++
>  Documentation/gpu/intel-display/index.rst    |  4 ++++
>  Documentation/gpu/intel-display/snps-phy.rst |  8 ++++++++
>  5 files changed, 39 insertions(+)
>  create mode 100644 Documentation/gpu/intel-display/atomic.rst
>  create mode 100644 Documentation/gpu/intel-display/casf.rst
>  create mode 100644 Documentation/gpu/intel-display/cmtg.rst
>  create mode 100644 Documentation/gpu/intel-display/snps-phy.rst
> 
> diff --git a/Documentation/gpu/intel-display/atomic.rst b/Documentation/gpu/intel-display/atomic.rst
> new file mode 100644
> index 000000000000..43a473181e7a
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/atomic.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Atomic Modeset Support
> +======================
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
> +   :doc: atomic modeset support
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
> +   :internal:

I believe they key functions on the other files below also deserves this
kind of doc. But I know, future work not related to this patch. ;)

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> diff --git a/Documentation/gpu/intel-display/casf.rst b/Documentation/gpu/intel-display/casf.rst
> new file mode 100644
> index 000000000000..406778ccd94c
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/casf.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Content Adaptive Sharpness Filter (CASF)
> +========================================
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_casf.c
> +   :doc: Content Adaptive Sharpness Filter (CASF)
> diff --git a/Documentation/gpu/intel-display/cmtg.rst b/Documentation/gpu/intel-display/cmtg.rst
> new file mode 100644
> index 000000000000..04edd0bd165d
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/cmtg.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Common Primary Timing Generator (CMTG)
> +======================================
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cmtg.c
> +   :doc: Common Primary Timing Generator (CMTG)
> diff --git a/Documentation/gpu/intel-display/index.rst b/Documentation/gpu/intel-display/index.rst
> index 8d40363b8f90..01c3d1e576b7 100644
> --- a/Documentation/gpu/intel-display/index.rst
> +++ b/Documentation/gpu/intel-display/index.rst
> @@ -24,8 +24,11 @@ driver. The display driver isn't an independent driver in that sense.
>     :caption: Detailed display topics
>  
>     async-flip
> +   atomic
>     audio
> +   casf
>     cdclk
> +   cmtg
>     dmc
>     dpio
>     dpll
> @@ -37,4 +40,5 @@ driver. The display driver isn't an independent driver in that sense.
>     hotplug
>     plane
>     psr
> +   snps-phy
>     vbt
> diff --git a/Documentation/gpu/intel-display/snps-phy.rst b/Documentation/gpu/intel-display/snps-phy.rst
> new file mode 100644
> index 000000000000..c9e333fa7f62
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/snps-phy.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +Synopsis PHY support
> +====================
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_snps_phy.c
> +   :doc: Synopsis PHY support
> -- 
> 2.47.3
> 

Re: [PATCH 1/3] Documentation/gpu: add dedicated documentation for Intel display

[Randy Dunlap]

On 5/8/26 3:20 AM, Jani Nikula wrote:
> diff --git a/Documentation/gpu/intel-display/index.rst b/Documentation/gpu/intel-display/index.rst
> new file mode 100644
> index 000000000000..8d40363b8f90
> --- /dev/null
> +++ b/Documentation/gpu/intel-display/index.rst
> @@ -0,0 +1,40 @@
> +.. SPDX-License-Identifier: MIT
> +.. Copyright © 2026 Intel Corporation
> +
> +.. _drm/intel-display:
> +
> +====================
> +Intel Display Driver
> +====================
> +
> +The Intel display driver provides the display, or :ref:`drm-kms`, support for
> +both the :ref:`drm/xe <drm/xe>` and :ref:`drm/i915 <drm/i915>` Intel GPU
> +drivers.
> +
> +The source code currently resides under ``drivers/gpu/drm/i915/display`` due to
> +historical reasons, and it's compiled separately into both drm/xe and drm/i915
> +kernel modules.
> +
> +The drm/xe and drm/i915 drivers are the "core" or "parent" drivers for display,
> +as they initialize and own the drm device, and pass that on to the display
> +driver. The display driver isn't an independent driver in that sense.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   :caption: Detailed display topics
> +
> +   async-flip
> +   audio
> +   cdclk
> +   dmc
> +   dpio
> +   dpll
> +   drrs
> +   dsb
> +   fbc
> +   fifo-underrun
> +   frontbuffer
> +   hotplug
> +   plane
> +   psr
> +   vbt

Is this in almost-alphabetical order or just random?  :)

Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

Re: [PATCH 2/3] Documentation/gpu: use === for Intel display section heading underlines

[Randy Dunlap]

On 5/8/26 3:20 AM, Jani Nikula wrote:
> Prefer to use === instead of --- for top level section heading
> underlines to allow using the latter for sub-headings later.
> 
> While at it, fix the underline lenghts where needed.

                                 lengths

> 
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>

 
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy