From patchwork Fri Aug 12 20:48:38 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9277905 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A5BA960231 for ; Fri, 12 Aug 2016 20:49:13 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9604628AEE for ; Fri, 12 Aug 2016 20:49:13 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8A34228AF2; Fri, 12 Aug 2016 20:49:13 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id AE08228AEE for ; Fri, 12 Aug 2016 20:49:12 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id AAE176EC1E; Fri, 12 Aug 2016 20:49:10 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-x241.google.com (mail-wm0-x241.google.com [IPv6:2a00:1450:400c:c09::241]) by gabe.freedesktop.org (Postfix) with ESMTPS id 8B5236EC1E for ; Fri, 12 Aug 2016 20:49:08 +0000 (UTC) Received: by mail-wm0-x241.google.com with SMTP id q128so5042411wma.1 for ; Fri, 12 Aug 2016 13:49:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=ruvj2GtSiurOFsRH6BAatGuFV6dPbPNfhvViK8oIM9w=; b=c9KgG1s2lgNSYeQwBwCDqnXELEr2Is2eLOvh/wohHzszkAh1ZPYRcfGt3L8UbOy1JD 6JjPgxMjBxDUXo20pFKuT/l3UTLl/gskfp2a+zAgcYUrSOpNSreuIoKSxKGEbF4YhwiO 0ZsuuRDwQ1WKsPF6UMwqnaq9S5B9QCocxva9A= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=ruvj2GtSiurOFsRH6BAatGuFV6dPbPNfhvViK8oIM9w=; b=I8pBNmikaUUleBq9F5uY3e72Fr4ViumqDOkXdiBEs+4gC6oJVno8lcJAeu6DtN+k8a S+XokE+LD9E32J/Bu0S6Z+kpMCN+BwEY73NADK5wfHXzlWOdr7FsU1UUlevhNrROAJmi Bya07s3aF+//g32JVUXp3QnecsKWRccboMkA6g/ZwOuLUWEYGd6R9nTmVbAoXe2RHhM2 z7EpvnlEVxVY9grcLzi+mgrBlfoVJmAK6fCrDqL4MInH70gpPDYimkEDp6cx9zJSnf9P E1ik8KfFVmP+XG3bFBNBeVtyPoGwKDOaSIvcYnUIPhMVtegmx4pB2D5UCV4SnnC4I+Hg x6Ug== X-Gm-Message-State: AEkooutrQ0DFWRIv5rJMZQpDJVDZSGFJaCZ/a9ydO1vxjWPmam9WF6ic4bgLTjV7uN7kiQ== X-Received: by 10.194.98.139 with SMTP id ei11mr17126334wjb.19.1471034946804; Fri, 12 Aug 2016 13:49:06 -0700 (PDT) Received: from phenom.ffwll.local ([2a02:168:56b5:0:ac27:b86c:7764:9429]) by smtp.gmail.com with ESMTPSA id s184sm4101485wmb.11.2016.08.12.13.49.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 12 Aug 2016 13:49:06 -0700 (PDT) From: Daniel Vetter To: DRI Development Subject: [PATCH 02/21] drm/doc: Light drm-kms-helper.rst cleanup Date: Fri, 12 Aug 2016 22:48:38 +0200 Message-Id: <1471034937-651-2-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.8.1 In-Reply-To: <1471034937-651-1-git-send-email-daniel.vetter@ffwll.ch> References: <1471034937-651-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Daniel Vetter X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP - Move the common vtable stuff to the top - Move "Tile Group" to a more appropriate heading level - Throw away the old intro for the crtc helpers (it's entirely stale, e.g. helpers have become modular years ago), and replace it with a general intro about the motivation behind helpers. - Reorder helpers to group them together a bit better, and explain that grouping in the intro. - Make sure the introductory DOC section is always first. v2: - Remove bogus files accidentally added (Sean). - Spelling fixes (Sean). Cc: Sean Paul Signed-off-by: Daniel Vetter Reviewed-by: Sean Paul --- Documentation/gpu/drm-kms-helpers.rst | 208 +++++++++++++++++----------------- Documentation/gpu/drm-uapi.rst | 3 + 2 files changed, 107 insertions(+), 104 deletions(-) diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..34f755bc9133 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 ` -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 `, :c:type:`struct -drm_encoder_funcs ` and :c:type:`struct -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,31 @@ 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 - -Tile group ----------- - -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group - -Bridges -======= - -Overview --------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: overview +Flip-work Helper Reference +========================== -Default bridge callback sequence --------------------------------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks +.. kernel-doc:: include/drm/drm_flip_work.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export: -Panel Helper Reference +Plane Helper Reference ====================== -.. kernel-doc:: include/drm/drm_panel.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_panel.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel - -Simple KMS Helper Reference -=========================== - -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +Tile group +========== -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :export: +# FIXME: This should probably be moved into a property documentation section -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 536bf3eaadd4..94876938aef3 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication .. kernel-doc:: include/drm/drm_auth.h :internal: +Open-Source Userspace Requirements +================================== + Render nodes ============