diff options
90 files changed, 4180 insertions, 3857 deletions
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..59fa3c11efab 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -2,38 +2,45 @@ Mode Setting Helper Functions ============================= -The plane, CRTC, encoder and connector functions provided by the drivers -implement the DRM API. They're called by the DRM core and ioctl handlers -to handle device state changes and configuration request. As -implementing those functions often requires logic not specific to -drivers, mid-layer helper functions are available to avoid duplicating -boilerplate code. - -The DRM core contains one mid-layer implementation. The mid-layer -provides implementations of several plane, CRTC, encoder and connector -functions (called from the top of the mid-layer) that pre-process -requests and call lower-level functions provided by the driver (at the -bottom of the mid-layer). For instance, the -:c:func:`drm_crtc_helper_set_config()` function can be used to -fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>` -set_config field. When called, it will split the set_config operation -in smaller, simpler operations and call the driver to handle them. - -To use the mid-layer, drivers call -:c:func:`drm_crtc_helper_add()`, -:c:func:`drm_encoder_helper_add()` and -:c:func:`drm_connector_helper_add()` functions to install their -mid-layer bottom operations handlers, and fill the :c:type:`struct -drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct -drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct -drm_connector_funcs <drm_connector_funcs>` structures with -pointers to the mid-layer top API functions. Installing the mid-layer -bottom operation handlers is best done right after registering the -corresponding KMS object. - -The mid-layer is not split between CRTC, encoder and connector -operations. To use it, a driver must provide bottom functions for all of -the three KMS entities. +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 +=========================================== + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :internal: + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :doc: overview Atomic Modeset Helper Functions Reference ========================================= @@ -62,33 +69,27 @@ Atomic State Reset and Initialization .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Modeset Helper Reference for Common Vtables -=========================================== - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview - Legacy CRTC/Modeset Helper Functions Reference ============================================== .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: + :doc: overview .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview + :export: -Output Probing Helper Functions Reference -========================================= +Simple KMS Helper Reference +=========================== -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c - :doc: output probing helper overview +.. kernel-doc:: include/drm/drm_simple_kms_helper.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + fbdev Helper Functions Reference ================================ @@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: +Bridges +======= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: overview + +Default bridge callback sequence +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge callbacks + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :export: + +Panel Helper Reference +====================== + +.. kernel-doc:: include/drm/drm_panel.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + Display Port Helper Functions Reference ======================================= @@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.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 =============================== @@ -176,18 +216,6 @@ Rectangle Utilities Reference .. 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: - HDMI Infoframes Helper Reference ================================ @@ -202,59 +230,40 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview +Flip-work Helper Reference +========================== -Tile group ----------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group +.. kernel-doc:: include/drm/drm_flip_work.h + :internal: -Bridges -======= +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c + :export: -Overview --------- +Plane Helper Reference +====================== -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :doc: overview -Default bridge callback sequence --------------------------------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export: -Panel Helper Reference -====================== - -.. kernel-doc:: include/drm/drm_panel.h - :internal: +Tile group +========== -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :export: +# FIXME: This should probably be moved into a property documentation section -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group -Simple KMS Helper Reference -=========================== +Auxiliary Modeset Helpers +========================= -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c + :doc: aux kms helpers -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c :export: - -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 8dfa4b214b96..fa948b4e029b 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -2,9 +2,6 @@ Kernel Mode Setting (KMS) ========================= -Mode Setting -============ - Drivers must initialize the mode setting core by calling :c:func:`drm_mode_config_init()` on the DRM device. The function initializes the :c:type:`struct drm_device <drm_device>` @@ -18,60 +15,50 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. -Display Modes Function Reference --------------------------------- +KMS Data Structures +=================== -.. kernel-doc:: include/drm/drm_modes.h +.. kernel-doc:: include/drm/drm_crtc.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_modes.c +KMS API Functions +================= + +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c :export: Atomic Mode Setting Function Reference --------------------------------------- +====================================== .. kernel-doc:: drivers/gpu/drm/drm_atomic.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c +.. kernel-doc:: include/drm/drm_atomic.h :internal: Frame Buffer Abstraction ------------------------- - -Frame buffers are abstract memory objects that provide a source of -pixels to scanout to a CRTC. Applications explicitly request the -creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls -and receive an opaque handle that can be passed to the KMS CRTC control, -plane configuration and page flip functions. - -Frame buffers rely on the underneath memory manager for low-level memory -operations. When creating a frame buffer applications pass a memory -handle (or a list of memory handles for multi-planar formats) through -the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their -userspace buffer management interface this would be a GEM handle. -Drivers are however free to use their own backing storage object -handles, e.g. vmwgfx directly exposes special TTM handles to userspace -and so expects TTM handles in the create ioctl and not GEM handles. - -The lifetime of a drm framebuffer is controlled with a reference count, -drivers can grab additional references with -:c:func:`drm_framebuffer_reference()`and drop them again with -:c:func:`drm_framebuffer_unreference()`. For driver-private -framebuffers for which the last reference is never dropped (e.g. for the -fbdev framebuffer when the struct :c:type:`struct drm_framebuffer -<drm_framebuffer>` is embedded into the fbdev helper struct) -drivers can manually clean up a framebuffer at module unload time with -:c:func:`drm_framebuffer_unregister_private()`. +======================== + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :doc: overview + +Frame Buffer Functions Reference +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :export: + +.. kernel-doc:: include/drm/drm_framebuffer.h + :internal: DRM Format Handling -------------------- +=================== .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: Dumb Buffer Objects -------------------- +=================== The KMS API doesn't standardize backing storage object creation and leaves it to driver-specific ioctls. Furthermore actually creating a @@ -114,14 +101,29 @@ Note that dumb objects may not be used for gpu acceleration, as has been attempted on some ARM embedded platforms. Such drivers really must have a hardware-specific ioctl to allocate suitable buffer objects. -Output Polling --------------- +Display Modes Function Reference |