From patchwork Thu Nov 1 13:45:16 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 1685081 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork1.kernel.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by patchwork1.kernel.org (Postfix) with ESMTP id E7D973FCDF for ; Thu, 1 Nov 2012 13:54:50 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id E696A9EF82 for ; Thu, 1 Nov 2012 06:54:50 -0700 (PDT) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-ee0-f49.google.com (mail-ee0-f49.google.com [74.125.83.49]) by gabe.freedesktop.org (Postfix) with ESMTP id D24C89E7D1 for ; Thu, 1 Nov 2012 06:53:51 -0700 (PDT) Received: by mail-ee0-f49.google.com with SMTP id c1so1312456eek.36 for ; Thu, 01 Nov 2012 06:53:50 -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:x-mailer:in-reply-to:references; bh=9dWSRI5P6Bs7ioShwt4TOnCIWfOUNY6+4W4zEGv+I2A=; b=S12KBOhQ+rOYxToTb/JMXVovIxxt1Mbnb162doQH9hMj3vkqrBpHhyD2iudx1/eU9m xrHAz/UkuDT3wADzzR7haj4MwlcKcOfW4MVfSQi6o6aopHbF39CCmhtZhs4LlgP8CKrC YWhpr/wgj3MIvyygMZJUbTzO/heAEtbJA7hcI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references :x-gm-message-state; bh=9dWSRI5P6Bs7ioShwt4TOnCIWfOUNY6+4W4zEGv+I2A=; b=BRgnTVCCeNgLIrvW3R3sctd9VVBGYl4XkoRX7Py9wamxU9piMjoIG7IDjtL+o2AGNo 9NcOOp0PyzOKHadcEuibNRaNwDcm19kNkRNazkWq0nIgWK7WsNDXnzZwF/gUxDnOWh0B MJge0UwZaatXKYxTlMy4qecoCHFHGrRxCTVHPx03sn2v0SIVYyr5OvC5mquSyvn6uioe ml4b928Ht7E+nxYHS+plfKYgfTS65oY/YLuXlaYZnP8YcyR+k0cegAV1ANt7VJgJ+nPG LcMK0er42KRpzewNd7Cgs/vLRX7Uw0VCGbU8Io5qAL5k81F/NVRxtgKC9BhqgypvY7fb gY7Q== Received: by 10.14.194.136 with SMTP id m8mr97536576een.10.1351778030703; Thu, 01 Nov 2012 06:53:50 -0700 (PDT) Received: from wespe.ffwll.local (178-83-130-250.dynamic.hispeed.ch. [178.83.130.250]) by mx.google.com with ESMTPS id k2sm14775358eep.15.2012.11.01.06.53.49 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 01 Nov 2012 06:53:50 -0700 (PDT) From: Daniel Vetter To: Dave Airlie Subject: [PATCH 2/4] drm/doc: integrate crtc helper api into docbook Date: Thu, 1 Nov 2012 14:45:16 +0100 Message-Id: <1351777518-11212-2-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 1.7.11.7 In-Reply-To: <1351777518-11212-1-git-send-email-daniel.vetter@ffwll.ch> References: <1351777518-11212-1-git-send-email-daniel.vetter@ffwll.ch> X-Gm-Message-State: ALoCoQnyS1iSeWsLEyVeV9lsjjJdmeqQKl5j7SRZ4XI8SK/CffNHUmAT8Q8jZB3kGKuD0MSf2BG9 Cc: Daniel Vetter , DRI Development X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: dri-devel-bounces+patchwork-dri-devel=patchwork.kernel.org@lists.freedesktop.org Errors-To: dri-devel-bounces+patchwork-dri-devel=patchwork.kernel.org@lists.freedesktop.org - Add the missing doc for drm_helper_move_panel_connectors_to_head. - Fixup any outdated stuff in existing sections. I've only looked at those kerneldoc headers that actually resulted in a complaint from the kerneldoc parser tool. v2: - Actually include the docbook snippet in the right patch. - Fix spelling fail. v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent Pinchart. Acked-by: Laurent Pinchart Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 4 +++ drivers/gpu/drm/drm_crtc_helper.c | 66 +++++++++++++++++++++++++-------------- 2 files changed, 46 insertions(+), 24 deletions(-) diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 270bc12..c2b31b9 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev) + + Modeset Helper Functions Reference +!Edrivers/gpu/drm/drm_crtc_helper.c + diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c index 7105168..2a7a886 100644 --- a/drivers/gpu/drm/drm_crtc_helper.c +++ b/drivers/gpu/drm/drm_crtc_helper.c @@ -39,6 +39,17 @@ #include #include +/** + * drm_helper_move_panel_connectors_to_head() - move panels to the front in the + * connector list + * @dev: drm device to operate on + * + * Some userspace presumes that the first connected connector is the main + * display, where it's supposed to display e.g. the login screen. For + * laptops, this should be the main panel. Use this function to sort all + * (eDP/LVDS) panels to the front of the connector list, instead of + * painstakingly trying to initialize them in the right order. + */ void drm_helper_move_panel_connectors_to_head(struct drm_device *dev) { struct drm_connector *connector, *tmp; @@ -82,22 +93,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector, /** * drm_helper_probe_single_connector_modes - get complete set of display modes - * @dev: DRM device + * @connector: connector to probe * @maxX: max width for modes * @maxY: max height for modes * * LOCKING: * Caller must hold mode config lock. * - * Based on @dev's mode_config layout, scan all the connectors and try to detect - * modes on them. Modes will first be added to the connector's probed_modes - * list, then culled (based on validity and the @maxX, @maxY parameters) and - * put into the normal modes list. - * - * Intended to be used either at bootup time or when major configuration - * changes have occurred. + * Based on the helper callbacks implemented by @connector try to detect all + * valid modes. Modes will first be added to the connector's probed_modes list, + * then culled (based on validity and the @maxX, @maxY parameters) and put into + * the normal modes list. * - * FIXME: take into account monitor limits + * Intended to be use as a generic implementation of the ->probe() @connector + * callback for drivers that use the crtc helpers for output mode filtering and + * detection. * * RETURNS: * Number of modes found on @connector. @@ -343,17 +353,24 @@ drm_crtc_prepare_encoders(struct drm_device *dev) } /** - * drm_crtc_set_mode - set a mode + * drm_crtc_helper_set_mode - internal helper to set a mode * @crtc: CRTC to program * @mode: mode to use * @x: width of mode * @y: height of mode + * @old_fb: old framebuffer, for cleanup * * LOCKING: * Caller must hold mode config lock. * * Try to set @mode on @crtc. Give @crtc and its associated connectors a chance - * to fixup or reject the mode prior to trying to set it. + * to fixup or reject the mode prior to trying to set it. This is an internal + * helper that drivers could e.g. use to update properties that require the + * entire output pipe to be disabled and re-enabled in a new configuration. For + * example for changing whether audio is enabled on a hdmi link or for changing + * panel fitter or dither attributes. It is also called by the + * drm_crtc_helper_set_config() helper function to drive the mode setting + * sequence. * * RETURNS: * True if the mode was set successfully, or false otherwise. @@ -509,20 +526,19 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) /** * drm_crtc_helper_set_config - set a new config from userspace - * @crtc: CRTC to setup - * @crtc_info: user provided configuration - * @new_mode: new mode to set - * @connector_set: set of connectors for the new config - * @fb: new framebuffer + * @set: mode set configuration * * LOCKING: * Caller must hold mode config lock. * - * Setup a new configuration, provided by the user in @crtc_info, and enable - * it. + * Setup a new configuration, provided by the upper layers (either an ioctl call + * from userspace or internally e.g. from the fbdev suppport code) in @set, and + * enable it. This is the main helper functions for drivers that implement + * kernel mode setting with the crtc helper functions and the assorted + * ->prepare(), ->modeset() and ->commit() helper callbacks. * * RETURNS: - * Zero. (FIXME) + * Returns 0 on success, -ERRNO on failure. */ int drm_crtc_helper_set_config(struct drm_mode_set *set) { @@ -818,12 +834,14 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc) } /** - * drm_helper_connector_dpms - * @connector affected connector - * @mode DPMS mode + * drm_helper_connector_dpms() - connector dpms helper implementation + * @connector: affected connector + * @mode: DPMS mode * - * Calls the low-level connector DPMS function, then - * calls appropriate encoder and crtc DPMS functions as well + * This is the main helper function provided by the crtc helper framework for + * implementing the DPMS connector attribute. It computes the new desired DPMS + * state for all encoders and crtcs in the output mesh and calls the ->dpms() + * callback provided by the driver appropriately. */ void drm_helper_connector_dpms(struct drm_connector *connector, int mode) {