From patchwork Wed Oct 31 10:01:35 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 1677891 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by patchwork2.kernel.org (Postfix) with ESMTP id 1036BDF2F6 for ; Wed, 31 Oct 2012 10:10:47 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id C27B8A0AF8 for ; Wed, 31 Oct 2012 03:10:46 -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 7B0EBA0AF4 for ; Wed, 31 Oct 2012 03:10:11 -0700 (PDT) Received: by mail-ee0-f49.google.com with SMTP id c1so643483eek.36 for ; Wed, 31 Oct 2012 03:10:10 -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=R798PkInXyUKpJbaI4XjHYlvhZ27Cm/1Tl/CFo28xc8=; b=BPLnGFJwfZaSdKcnV9p99XCQ6bIjXcf/+RYiPTyZlyvXRNnwQkSFCXpp4YErTQbofl 0B2rgJtq7ATMm1E/jI3W+sDb5oJGbb2XhweIs5ABjpIShMNzn2Ijn0q1uMld2GY1Fr6Y HIEjo0ewD74Cimx1Hyc8K+7nm+D632M2U32iQ= 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=R798PkInXyUKpJbaI4XjHYlvhZ27Cm/1Tl/CFo28xc8=; b=olq/TzRctcAavfsdHLwDVeDkFCpGtRaPw2NDQg6IJk600SPikOat8Tk5tXtYq/tWkg hJt+sDGLo2SUA8zg8vcScq+7kqtL3T6ZGQc71OgA2HaIOS+Di11RhSzLcIoR9me9MCXc S1JqU9tuBO75htcVqLJ6S8wocI21yQlVlrZ54DWPvkumanTTTRTOcMGiUm7QpL5QDaFQ udCTtxEBNI/RE1UVrPkJgQqb8VD8e48+E9bcafoGbx6jkzh5kraf4IRtF4vsLbGkvK4q 5WusaMlPbGHVtS7YLpElwF5hAEdMWqmQHcIbKX6+aFepOj1CabRcObmFihx8LV02kUh+ WREA== Received: by 10.14.219.2 with SMTP id l2mr78906029eep.3.1351678210629; Wed, 31 Oct 2012 03:10:10 -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 f2sm7045485eep.2.2012.10.31.03.10.09 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 31 Oct 2012 03:10:09 -0700 (PDT) From: Daniel Vetter To: DRI Development Subject: [PATCH 1/3] drm/doc: integrate crtc helper api into docbook Date: Wed, 31 Oct 2012 11:01:35 +0100 Message-Id: <1351677697-13953-1-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 1.7.11.7 In-Reply-To: <1351674710-11629-1-git-send-email-daniel.vetter@ffwll.ch> References: <1351674710-11629-1-git-send-email-daniel.vetter@ffwll.ch> X-Gm-Message-State: ALoCoQnSH9xdLFYBiLlup8DJH31hqKOesKmr3+msxPsTR0TPIkF09sK84sMgc+8YT2yK04MJlT1m Cc: Daniel Vetter , Laurent Pinchart 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. 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 ca45155..43e706e 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..df4aba1 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_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) {