Mode Setting Helper Functions

Mode setting helper의 역할과 세 분류

DRM subsystem은 core code와 helper library를 강하게 분리하는 것을 목표로 합니다. Core code는 일반적인 setup·teardown과 userspace request를 kernel 내부 object로 해석하는 일을 담당합니다. 그 밖의 기능은 큰 helper library 집합이 처리하며, driver는 필요한 helper를 자유롭게 조합하고 특수 동작이 필요한 곳에서는 shared code를 피할 수 있습니다.

이 구분은 모든 driver가 공유하는 userspace ABI가 있는 modesetting code에서 특히 강합니다. 반대로 render 쪽은 극소수의 예외를 제외하면 거의 모든 기능을 선택 가능한 helper code로 볼 수 있습니다.

첫 helper군은 modesetting 구현을 담당합니다. 핵심은 atomic helper이고 오래된 driver는 legacy CRTC helper를 여전히 많이 사용합니다. 두 방식은 공통 helper vtable 집합을 공유합니다. Deprecated된 fbdev subsystem에 잘 맞았을 정도로 단순한 driver에는 simple display pipe helper도 있습니다.

두 번째 helper군은 output을 처리합니다. Encoder·transcoder IP block을 다루는 generic bridge helper, panel 정보와 logic을 다루는 panel helper, DisplayPort·HDMI·MIPI DSI sink 표준별 helper, output probing과 EDID helper가 포함됩니다.

마지막 helper군은 display pipeline의 frontend를 다룹니다. Plane, visibility 검사와 scissoring을 위한 rectangle 처리, flip queue와 기타 보조 기능이 이 범주에 속합니다.

=============================
Mode Setting Helper Functions
=============================

The DRM subsystem aims for a strong separation between core code and helper
libraries. Core code takes care of general setup and teardown and decoding
userspace requests to kernel internal objects. Everything else is handled by a
large set of helper libraries, which can be combined freely to pick and choose
for each driver what fits, and avoid shared code where special behaviour is
needed.

This distinction between core code and helpers is especially strong in the
modesetting code, where there's a shared userspace ABI for all drivers. This is
in contrast to the render side, where pretty much everything (with very few
exceptions) can be considered optional helper code.

There are a few areas these helpers can grouped into:

* Helpers to implement modesetting. The important ones here are the atomic
  helpers. Old drivers still often use the legacy CRTC helpers. They both share
  the same set of common helper vtables. For really simple drivers (anything
  that would have been a great fit in the deprecated fbdev subsystem) there's
  also the simple display pipe helpers.

* There's a big pile of helpers for handling outputs. First the generic bridge
  helpers for handling encoder and transcoder IP blocks. Second the panel helpers
  for handling panel-related information and logic. Plus then a big set of
  helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
  there's also generic helpers for handling output probing, and for dealing with
  EDIDs.

* The last group of helpers concerns itself with the frontend side of a display
  pipeline: Planes, handling rectangles for visibility checking and scissoring,
  flip queues and assorted bits.

Modeset Helper Reference for Common Vtables
===========================================

공통 vtable, atomic state와 VBLANK helper

공통 vtable reference는 `drm_modeset_helper_vtables.h`의 overview와 내부 interface를 제공합니다. Atomic helper reference는 전체 개요, nonblocking commit 구현, 내부 declaration과 exported API를 결합합니다.

Atomic state helper는 state reset·initialization 문서와 exported helper를 제공하고, GEM atomic helper는 GEM object를 atomic modeset 흐름에 연결하는 개요·내부 interface·exported API를 제공합니다.

VBLANK helper reference는 `drm_vblank_helper.c`의 overview와 exported API, `drm_vblank_helper.h`의 내부 declaration을 포함해 vertical blanking 관련 helper를 한곳에 모읍니다.

.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
   :doc: overview

.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
   :internal:

.. _drm_atomic_helper:

Atomic Modeset Helper Functions Reference
=========================================

Overview
--------

.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
   :doc: overview

Implementing Asynchronous Atomic Commit
---------------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
   :doc: implementing nonblocking commit

Helper Functions Reference
--------------------------

.. kernel-doc:: include/drm/drm_atomic_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
   :export:

Atomic State Reset and Initialization
-------------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
   :doc: atomic state reset and initialization

Atomic State Helper Reference
-----------------------------

.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c
   :export:

GEM Atomic Helper Reference
---------------------------

.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
   :doc: overview

.. kernel-doc:: include/drm/drm_gem_atomic_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c
   :export:

VBLANK Helper Reference
-----------------------

.. kernel-doc:: drivers/gpu/drm/drm_vblank_helper.c
   :doc: overview

.. kernel-doc:: include/drm/drm_vblank_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_vblank_helper.c
   :export:

Simple KMS와 framebuffer helper

Simple KMS helper는 단순한 display pipeline을 위한 overview, 내부 interface, exported API를 제공합니다. fbdev helper는 DRM driver가 fbdev compatibility를 제공할 때 사용하는 설명과 API를 모읍니다.

Format helper는 pixel format 변환·처리용 exported API를 제공합니다. Framebuffer DMA helper는 DMA-backed framebuffer 기능을, GEM framebuffer helper는 GEM-backed framebuffer 기능을 각각 설명과 exported 함수로 제공합니다.

Simple KMS Helper Reference
===========================

.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
   :doc: overview

.. kernel-doc:: include/drm/drm_simple_kms_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
   :export:

fbdev Helper Functions Reference
================================

.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
   :doc: fbdev helpers

.. kernel-doc:: include/drm/drm_fb_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
   :export:

format Helper Functions Reference
=================================

.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c
   :export:

Framebuffer DMA Helper Functions Reference
==========================================

.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
   :doc: framebuffer dma helper functions

.. kernel-doc:: drivers/gpu/drm/drm_fb_dma_helper.c
   :export:

Framebuffer GEM Helper Reference
================================

.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
   :export:

Bridge·panel과 self-refresh helper

Bridge 절은 generic bridge의 overview, display driver integration, MIPI-DSI bridge에서 특별히 주의할 점, bridge operation과 DSI bridge operation을 설명합니다. Bridge connector helper는 bridge chain을 connector로 노출하는 개요와 exported API를 제공합니다.

`drm_bridge.h` 내부 interface와 `drm_bridge.c` exported API가 일반 bridge operation을 구성하고, `drivers/gpu/drm/bridge/panel.c`는 panel을 bridge로 다루는 helper를 제공합니다.

Panel helper reference는 DRM panel 개요, `drm_panel.h` 내부 interface, panel exported API, orientation quirk와 backlight quirk API를 결합합니다. Panel self-refresh helper는 self-refresh 동작의 overview와 exported API를 제공합니다.

.. _drm_bridges:

Bridges
=======

Overview
--------

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :doc: overview

Display Driver Integration
--------------------------

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :doc: display driver integration

Special Care with MIPI-DSI bridges
----------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :doc: special care dsi

Bridge Operations
-----------------

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :doc: bridge operations

Bridge Connector Helper
-----------------------

.. kernel-doc:: drivers/gpu/drm/display/drm_bridge_connector.c
   :doc: overview


Bridge Helper Reference
-------------------------

.. kernel-doc:: include/drm/drm_bridge.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :export:

MIPI-DSI bridge operation
-------------------------

.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
   :doc: dsi bridge operations


Bridge Connector Helper Reference
---------------------------------

.. kernel-doc:: drivers/gpu/drm/display/drm_bridge_connector.c
   :export:

Panel-Bridge Helper Reference
-----------------------------

.. kernel-doc:: drivers/gpu/drm/bridge/panel.c
   :export:

.. _drm_panel_helper:

Panel Helper Reference
======================

.. kernel-doc:: drivers/gpu/drm/drm_panel.c
   :doc: drm panel

.. kernel-doc:: include/drm/drm_panel.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_panel.c
   :export:

.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
   :export:

.. kernel-doc:: drivers/gpu/drm/drm_panel_backlight_quirks.c
   :export:

Panel Self Refresh Helper Reference
===================================

.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c
   :export:

HDMI·HDCP·DisplayPort와 MST topology

HDMI atomic state helper는 HDMI state를 atomic modeset에 연결하는 설명과 함수 reference를 제공합니다. HDCP helper 절은 content protection 처리용 exported API를 포함합니다.

DisplayPort helper는 DP 개요, protocol type과 내부 helper declaration, exported API를 결합합니다. 별도 절은 DP CEC, dual-mode adaptor의 개요·내부 interface·exported API를 제공합니다.

DP MST helper는 MST topology 개요와 branch device·port refcounting 문서, 내부 header와 exported API를 포함합니다. Topology lifetime 내부 함수는 driver에 export되지 않지만 MST topology helper의 lifetime을 이해하기 쉽도록 이 문서에 명시적으로 포함됩니다.

`:functions:` 목록은 `drm_dp_mst_topology_try_get_mstb`, `drm_dp_mst_topology_get_mstb`, `drm_dp_mst_topology_put_mstb`, port의 try/get/put 함수, malloc된 MST branch의 get/put 함수를 정확히 선택합니다.

HDMI Atomic State Helpers
=========================

Overview
--------

.. kernel-doc:: drivers/gpu/drm/display/drm_hdmi_state_helper.c
   :doc: hdmi helpers

Functions Reference
-------------------

.. kernel-doc:: drivers/gpu/drm/display/drm_hdmi_state_helper.c
   :export:

HDCP Helper Functions Reference
===============================

.. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c
   :export:

Display Port Helper Functions Reference
=======================================

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
   :doc: dp helpers

.. kernel-doc:: include/drm/display/drm_dp.h
   :internal:

.. kernel-doc:: include/drm/display/drm_dp_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c
   :export:

Display Port CEC Helper Functions Reference
===========================================

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
   :doc: dp cec helpers

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c
   :export:

Display Port Dual Mode Adaptor Helper Functions Reference
=========================================================

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
   :doc: dp dual mode helpers

.. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c
   :export:

Display Port MST Helpers
========================

Overview
--------

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
   :doc: dp mst helper

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
   :doc: Branch device and port refcounting

Functions Reference
-------------------

.. kernel-doc:: include/drm/display/drm_dp_mst_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
   :export:

Topology Lifetime Internals
---------------------------

These functions aren't exported to drivers, but are documented here to help make
the MST topology helpers easier to understand

.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c
   :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb
               drm_dp_mst_topology_put_mstb
               drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port
               drm_dp_mst_topology_put_port
               drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc

MIPI·DSC·output probing·EDID·SCDC

MIPI DBI와 MIPI DSI 절은 각 protocol helper의 overview, 내부 header, exported API를 제공합니다. Display Stream Compression(DSC) 절도 같은 구조로 DSC 설명과 data structure, helper API를 결합합니다.

Output probing helper는 connector와 output 탐색 흐름의 개요·exported API를 제공합니다. EDID helper는 `drm_edid.h`와 `drm_eld.h`의 내부 interface, EDID·ELD 구현의 exported API를 모읍니다.

SCDC helper는 HDMI sink의 Status and Control Data Channel을 다루는 개요, 내부 header, exported API를 제공합니다.

MIPI DBI Helper Functions Reference
===================================

.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
   :doc: overview

.. kernel-doc:: include/drm/drm_mipi_dbi.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c
   :export:

MIPI DSI Helper Functions Reference
===================================

.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
   :doc: dsi helpers

.. kernel-doc:: include/drm/drm_mipi_dsi.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
   :export:

Display Stream Compression Helper Functions Reference
=====================================================

.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
   :doc: dsc helpers

.. kernel-doc:: include/drm/display/drm_dsc.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c
   :export:

Output Probing Helper Functions Reference
=========================================

.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
   :doc: output probing helper overview

.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
   :export:

EDID Helper Functions Reference
===============================

.. kernel-doc:: include/drm/drm_edid.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_edid.c
   :export:

.. kernel-doc:: include/drm/drm_eld.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_eld.c
   :export:

SCDC Helper Functions Reference
===============================

.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
   :doc: scdc helpers

.. kernel-doc:: include/drm/display/drm_scdc_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c
   :export:

HDMI infoframe, rectangle과 flip-work

엄밀히 말해 HDMI Infoframe code는 DRM helper library가 아니라 HDMI output에 연결되는 모든 driver가 일반적으로 사용할 수 있습니다. 여기에는 V4L이나 ALSA driver도 포함됩니다. 그러나 mode setting helper library라는 전체 주제에 잘 맞기 때문에 이 문서에 함께 수록합니다.

HDMI header의 내부 interface와 `drivers/video/hdmi.c` exported API가 infoframe 기능을 제공합니다. Rectangle utility는 visibility와 clipping 계산에 쓰이는 rectangle helper를, flip-work helper는 비동기 flip 관련 work 처리를 위한 개요·내부 interface·exported API를 제공합니다.

HDMI Infoframes Helper Reference
================================

Strictly speaking this is not a DRM helper library but generally usable
by any driver interfacing with HDMI outputs like v4l or alsa drivers.
But it nicely fits into the overall topic of mode setting helper
libraries and hence is also included here.

.. kernel-doc:: include/linux/hdmi.h
   :internal:

.. kernel-doc:: drivers/video/hdmi.c
   :export:

Rectangle Utilities Reference
=============================

.. kernel-doc:: include/drm/drm_rect.h
   :doc: rect utils

.. kernel-doc:: include/drm/drm_rect.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_rect.c
   :export:

Flip-work Helper Reference
==========================

.. kernel-doc:: include/drm/drm_flip_work.h
   :doc: flip utils

.. kernel-doc:: include/drm/drm_flip_work.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
   :export:

보조 modeset, OF/DT, legacy와 privacy-screen

Auxiliary modeset helper는 기타 KMS helper의 개요와 exported API를 제공합니다. OF/DT helper는 device tree 기반 display 구성에 쓰이는 overview와 exported API를 제공합니다.

Legacy plane helper와 legacy CRTC/modeset helper는 각각 오래된 plane·CRTC driver model의 overview와 exported API를 문서화합니다. 새 atomic driver를 설계할 때는 legacy라는 범위를 분명히 인식해야 합니다.

Privacy-screen class는 privacy screen core의 overview·exported API와 driver용·machine용 내부 header를 결합해 panel privacy filter를 제어하는 class interface를 설명합니다.

Auxiliary Modeset Helpers
=========================

.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
   :doc: aux kms helpers

.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
   :export:

OF/DT Helpers
=============

.. kernel-doc:: drivers/gpu/drm/drm_of.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_of.c
   :export:

Legacy Plane Helper Reference
=============================

.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
   :export:

Legacy CRTC/Modeset Helper Functions Reference
==============================================

.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
   :export:

Privacy-screen class
====================

.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
   :doc: overview

.. kernel-doc:: include/drm/drm_privacy_screen_driver.h
   :internal:

.. kernel-doc:: include/drm/drm_privacy_screen_machine.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_privacy_screen.c
   :export: