From patchwork Wed Aug 17 20:56:02 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9286577 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 2E7E760839 for ; Wed, 17 Aug 2016 20:56:32 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2094C293C0 for ; Wed, 17 Aug 2016 20:56:32 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 15A9E293D9; Wed, 17 Aug 2016 20:56:32 +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 63ED5293C0 for ; Wed, 17 Aug 2016 20:56:27 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 8369D6E92E; Wed, 17 Aug 2016 20:56:22 +0000 (UTC) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-wm0-x242.google.com (mail-wm0-x242.google.com [IPv6:2a00:1450:400c:c09::242]) by gabe.freedesktop.org (Postfix) with ESMTPS id D92C56E92D for ; Wed, 17 Aug 2016 20:56:20 +0000 (UTC) Received: by mail-wm0-x242.google.com with SMTP id i138so969974wmf.3 for ; Wed, 17 Aug 2016 13:56:20 -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=mIebQ/fL1FJVLCfyjv4qUXALJ0RXVEU5U7kTHmjBs88=; b=SpNV2p9JyVhw1R/8V8l7m3YeUXZBWMqIjUTmhjU296w5sr18iXLRG0wo9cQ+ZoFbKp F6DiareoE8PBol+EvCrfVLrw9NJG6cxFUrsdtft7d2UEv/vSNfQPfHuC0ypQn/vNKNdr Hqqp+1k8/FDzfKLV+FC3TO+aeirwwfcLGBjzA= 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=mIebQ/fL1FJVLCfyjv4qUXALJ0RXVEU5U7kTHmjBs88=; b=WZqpT/i4jrOZMcuQHE9v2mEvDMkhvvbwTcEkDU2rBC96PE/T4MRk0GquHG92B5Zy0l 1TFX11TxXBtZBbceO28YmgpULhbHoN8vPNIvLd7n3NhSu5H6zREzVdxEiDW4zpqHsk7c w5xM50uTAlJyOHkAPkGmp/6dRjhSFLX9wU1KGoqkd6UOATPulTYsbcGYoYz0uhe+gHpG YsZQ+cnwNUwKabnhy2VEAhR/x+R/CcRvLzgaf3RixOsKr3PfXskMJpxwbPU8geopMGA1 S6YAthlA8Biz1TZiQzN5tMjSkS6vqxjtM2kfDJ5MDIYcsrruuxty0GNfHHDwgUefoLu+ ZvBQ== X-Gm-Message-State: AEkooutT3XCAj7of4L2iwHiQGFoANPgj6R+Aaev90dGkdRVuLfrOIWajCUo9r/w4Mr5zsw== X-Received: by 10.194.161.70 with SMTP id xq6mr15356132wjb.189.1471467379425; Wed, 17 Aug 2016 13:56:19 -0700 (PDT) Received: from phenom.ffwll.local ([2a02:168:56b5:0:ac27:b86c:7764:9429]) by smtp.gmail.com with ESMTPSA id a203sm239519wma.0.2016.08.17.13.56.18 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 17 Aug 2016 13:56:18 -0700 (PDT) From: Daniel Vetter To: DRI Development Date: Wed, 17 Aug 2016 22:56:02 +0200 Message-Id: <1471467366-26444-5-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.8.1 In-Reply-To: <1471467366-26444-1-git-send-email-daniel.vetter@ffwll.ch> References: <1471467366-26444-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Intel Graphics Development Subject: [Intel-gfx] [PATCH 5/9] drm/doc: Polish docs for drm_mode_object X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Virus-Scanned: ClamAV using ClamSMTP I figured an overview section here is overkill, and better to just document the 2 structures themselves well enough. Signed-off-by: Daniel Vetter Reviewed-by: Archit Taneja --- drivers/gpu/drm/drm_mode_object.c | 9 +++++++ include/drm/drm_mode_object.h | 50 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/drivers/gpu/drm/drm_mode_object.c b/drivers/gpu/drm/drm_mode_object.c index a92aeed51156..a4dd3fa258b4 100644 --- a/drivers/gpu/drm/drm_mode_object.c +++ b/drivers/gpu/drm/drm_mode_object.c @@ -222,6 +222,12 @@ EXPORT_SYMBOL(drm_object_attach_property); * changes the software state of the property, it does not call into the * driver's ->set_property callback. * + * Note that atomic drivers should not have any need to call this, the core will + * ensure consistency of values reported back to userspace through the + * appropriate ->atomic_get_property callback. Only legacy drivers should call + * this function to update the tracked value (after clamping and other + * restrictions have been applied). + * * Returns: * Zero on success, error code on failure. */ @@ -252,6 +258,9 @@ EXPORT_SYMBOL(drm_object_property_set_value); * value this might be out of sync with the hardware, depending upon the driver * and property. * + * Atomic drivers should never call this function directly, the core will read + * out property values through the various ->atomic_get_property callbacks. + * * Returns: * Zero on success, error code on failure. */ diff --git a/include/drm/drm_mode_object.h b/include/drm/drm_mode_object.h index b8adb6425f2a..7967ffeda3c4 100644 --- a/include/drm/drm_mode_object.h +++ b/include/drm/drm_mode_object.h @@ -27,6 +27,28 @@ struct drm_object_properties; struct drm_property; +/** + * struct drm_mode_object - base structure for modeset objecst + * @id: userspace visible identifier + * @type: type of the object, one of DRM_MODE_OBJECT\_\* + * @properties: properties attached to this object, including values + * @refcount: reference count for objects which with dynamic lifetime + * @free_cb: free function callback, only set for objects with dynamic lifetime + * + * Base structure for modeset objects visible to userspace. Objects can be + * looked up using drm_mode_object_find(). Besides basic uapi interface + * properties like @id and @type it provides two servies: + * + * - It tracks attached properties and their values. This is used by &drm_crtc, + * &drm_plane and &drm_connector. Properties are attached by calling + * drm_object_attach_property() before the object is visible to userspace. + * + * - For objects with dynamic lifetimes (as indicated by a non-NULL @free_cb) it + * provides reference counting through drm_mode_object_reference() and + * drm_mode_object_unreference(). This is used by &drm_framebuffer, + * &drm_connector and &drm_property_blob. These objects provide specialized + * reference counting wrappers. + */ struct drm_mode_object { uint32_t id; uint32_t type; @@ -36,16 +58,38 @@ struct drm_mode_object { }; #define DRM_OBJECT_MAX_PROPERTY 24 +/** + * struct drm_object_properties - property tracking for &drm_mode_object + */ struct drm_object_properties { + /** + * @count: number of valid properties, must be less than or equal to + * DRM_OBJECT_MAX_PROPERTY. + */ + int count; - /* NOTE: if we ever start dynamically destroying properties (ie. + /** + * @properties: Array of pointers to &drm_property. + * + * NOTE: if we ever start dynamically destroying properties (ie. * not at drm_mode_config_cleanup() time), then we'd have to do * a better job of detaching property from mode objects to avoid * dangling property pointers: */ struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY]; - /* do not read/write values directly, but use drm_object_property_get_value() - * and drm_object_property_set_value(): + + /** + * @values: Array to store the property values, matching @properties. Do + * not read/write values directly, but use + * drm_object_property_get_value() and drm_object_property_set_value(). + * + * Note that atomic drivers do not store mutable properties in this + * aray, but only the decoded values in the corresponding state + * structure. The decoding is done using the ->atomic_get_property and + * ->atomic_set_property hooks of the corresponding object. Hence atomic + * drivers should not use drm_object_property_set_value() and + * drm_object_property_get_value() on mutable objects, i.e. those + * without the DRM_MODE_PROP_IMMUTABLE flag set. */ uint64_t values[DRM_OBJECT_MAX_PROPERTY]; };