From patchwork Fri Dec 4 08:46:01 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7766781 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 59CB6BEEE5 for ; Fri, 4 Dec 2015 08:47:00 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 0C2BF20525 for ; Fri, 4 Dec 2015 08:46:59 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 0E04620498 for ; Fri, 4 Dec 2015 08:46:58 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 4B7B58A821; Fri, 4 Dec 2015 00:46:44 -0800 (PST) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-f45.google.com (mail-wm0-f45.google.com [74.125.82.45]) by gabe.freedesktop.org (Postfix) with ESMTPS id D65618A80C for ; Fri, 4 Dec 2015 00:46:39 -0800 (PST) Received: by wmww144 with SMTP id w144so55372428wmw.0 for ; Fri, 04 Dec 2015 00:46:38 -0800 (PST) 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=AMFppyQTPhEVv4FlNG1QoJiw/kA2ZfgbJwBK+7yxhsM=; b=CweFifkWBBQ3D1nAZ5EQnADBSjzgOSvOW/4owYemz5I8qvIP2Db0qmsYArSyLOfM5w Jd59rEfW/hPCNZDQF8rC9CQE0N0zArDvkf6GNszdUFUg9yum+v0EUKicF0TzEX+eYI3j baLDFz4NSyf4StwkeljfHZnKzrDwPXUiwIGB4= 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=AMFppyQTPhEVv4FlNG1QoJiw/kA2ZfgbJwBK+7yxhsM=; b=aqdH2YJCo28WEh/yyYPdxEr8fishxWhH1GtZPryDss4FbA5mTAbHnH3QMVKDLO3+pt tjXk0qq9DCe2xrAIZtMltewD+d8pX/2cLT/EAdBbEITjVAzO9NzmPRQKgLGPo03adEVJ S18rBWSLSvN+fCScDf8N4K1n1JoLFmg6e6x8Thpzj+bd23GuJVS4n4gEbYl2yqYexZ2c YqCCynM3aCqdbTiBRW1Vqh62xqLACwD81kE6GPxyeWps2oOMj6GOXDpQkxPZvTiiD9bz +kToa5YW9nML1nJLx56TFp5eMxaMMvL7mY/KCsq0wMJu5voFxKT2/tfGLXGjenHBCue7 FWUA== X-Gm-Message-State: ALoCoQkGIojMqGfOJbuDEaVIHPlMRo1TEBwTdhoUuM4JiwenayEpPD0WXTpKEGh3ZBzNDHXq9hrJ X-Received: by 10.194.82.99 with SMTP id h3mr18447466wjy.41.1449218798666; Fri, 04 Dec 2015 00:46:38 -0800 (PST) Received: from phenom.ffwll.local (212-51-149-109.fiber7.init7.net. [212.51.149.109]) by smtp.gmail.com with ESMTPSA id pc2sm6926311wjb.11.2015.12.04.00.46.37 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 04 Dec 2015 00:46:37 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 20/28] drm: Add kerneldoc for drm_framebuffer_funcs Date: Fri, 4 Dec 2015 09:46:01 +0100 Message-Id: <1449218769-16577-21-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1449218769-16577-1-git-send-email-daniel.vetter@ffwll.ch> References: <1449218769-16577-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Intel Graphics Development 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-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP While typing these I noticed that ->dirty is a bit a can of worms and even supports blt/fill semantics ... shocked me a bit. Oh well it's defined in a way that nothing bad (just a bit of inefficiency) will happen for drivers which supports this. So I didn't bother copying the detailed spec into the new kerneldoc. Signed-off-by: Daniel Vetter Reviewed-by: Thierry Reding --- include/drm/drm_crtc.h | 50 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h index 72a7e096dd42..551484fb55e5 100644 --- a/include/drm/drm_crtc.h +++ b/include/drm/drm_crtc.h @@ -162,23 +162,55 @@ struct drm_tile_group { u8 group_data[8]; }; +/** + * struct drm_framebuffer_funcs - framebuffer hooks + */ struct drm_framebuffer_funcs { - /* note: use drm_framebuffer_remove() */ + /** + * @destroy: + * + * Clean up framebuffer resources, specifically also unreference the + * backing storage. The core guarantees to call this function for every + * framebuffer succesfully created by fb_create in + * &drm_mode_config_funcs. + */ void (*destroy)(struct drm_framebuffer *framebuffer); + + /** + * @create_handle: + * + * Create a buffer handle in the driver-specific buffer manager (either + * GEM or TTM) valid for the passed-in struct &drm_file. This is used by + * the core to implement the GETFB ioctl, which returns (for + * sufficiently priviledged user) also a native buffer handle. This can + * be used for seamless transitions between modesetting clients by + * copying the current screen contents to a private buffer and blending + * between that and the new contents. + * + * RETURNS: + * + * 0 on success or a negative error code on failure. + */ int (*create_handle)(struct drm_framebuffer *fb, struct drm_file *file_priv, unsigned int *handle); - /* + /** + * @dirty: + * * Optional callback for the dirty fb ioctl. * - * Userspace can notify the driver via this callback - * that a area of the framebuffer has changed and should - * be flushed to the display hardware. + * Userspace can notify the driver via this callback that a area of the + * framebuffer has changed and should be flushed to the display + * hardware. This can also be used internally, e.g. by the fbdev + * emulation, though that's not (yet) the case currently. + * + * See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd + * for more information as all the semantics and arguments have a one to + * one mapping on this function. * - * See documentation in drm_mode.h for the struct - * drm_mode_fb_dirty_cmd for more information as all - * the semantics and arguments have a one to one mapping - * on this function. + * RETURNS: + * + * 0 on success or a negative error code on failure. */ int (*dirty)(struct drm_framebuffer *framebuffer, struct drm_file *file_priv, unsigned flags,