From patchwork Thu Oct 22 17:11:29 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7466081 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 150E2BEEA4 for ; Thu, 22 Oct 2015 17:11:58 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 312C520963 for ; Thu, 22 Oct 2015 17:11:53 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 606F92094C for ; Thu, 22 Oct 2015 17:11:51 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 7B00F6E3BD; Thu, 22 Oct 2015 10:11:47 -0700 (PDT) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wi0-f174.google.com (mail-wi0-f174.google.com [209.85.212.174]) by gabe.freedesktop.org (Postfix) with ESMTPS id 8FC2E6E368 for ; Thu, 22 Oct 2015 10:11:46 -0700 (PDT) Received: by wicfv8 with SMTP id fv8so130001682wic.0 for ; Thu, 22 Oct 2015 10:11:45 -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=0ajmdThtn1atKNa4Z+tNDFsMQb4BsWxpXvRJrtRshws=; b=O0xR6zeG4mOQNAVubod3yCLWPzkai6q5738oehr5RqfvI7ASiyUKomrbynztSRBFhD VqSgSkKXv06cYVP2leAHLikfF0LWIVqIv2jD5T8AOPzQ8uGtTdK3WAdkZr0ci1qspdMD L1RR2z9SfnTC75R+YDsb0DphKFbZEy+1s7OlU= 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=0ajmdThtn1atKNa4Z+tNDFsMQb4BsWxpXvRJrtRshws=; b=Sw9h59yuIEUvRhbDCsGKGT1Hr2VY1msTI3bwT4qtAhg+CjHQg239TDL+oPtDIJV543 l+X519jfCv83wgEBzwkLGct0EorWUYNhJoS+E6ysQfYvINhg0urbU+IYRhVt+QNCQLCP /NYlR5T9uT8k3PcQuSXB9nknv0/PwIrrxWiaTgYw6GtRbIuZ0hWF9qwSNYm8n+U5gSId Yr+UsDW2jbHlfmAysh0/VIl+liqYMD5vKkBzS0wJ8tEllf9xkdLhyNscA8LEiimvHc2j sHo9cJxw/FRxydmQxUet39TPpdOU+u81CX1GhEoNw3nlfQrvCIiwVWskvkgmoJwKWe6I OCqA== X-Gm-Message-State: ALoCoQkLxYqsgnY7tvtWfP0658luKnMDyt+jBjeDaVkBVaYUNELcFSf+Z/tzRn2+1iDPgV+2OTeX X-Received: by 10.180.8.106 with SMTP id q10mr17721931wia.92.1445533905153; Thu, 22 Oct 2015 10:11:45 -0700 (PDT) Received: from phenom.ffwll.local (212-51-149-109.fiber7.init7.net. [212.51.149.109]) by smtp.gmail.com with ESMTPSA id hs5sm28838857wib.6.2015.10.22.10.11.44 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 22 Oct 2015 10:11:44 -0700 (PDT) From: Daniel Vetter To: DRI Development Subject: [PATCH 3/3] drm/gem: Update/Polish docs Date: Thu, 22 Oct 2015 19:11:29 +0200 Message-Id: <1445533889-7661-3-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1445533889-7661-1-git-send-email-daniel.vetter@ffwll.ch> References: <1445533889-7661-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Intel Graphics Development , 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-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,RP_MATCHES_RCVD,T_DKIM_INVALID,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 A bunch of things have been removed meanwhile and docs not fully brought up to speed. And a few gaps closed where I noticed missing kerneldoc while reading through the overview sections. Signed-off-by: Daniel Vetter --- Documentation/DocBook/gpu.tmpl | 33 ++++----------------------------- drivers/gpu/drm/drm_gem.c | 35 ++++++++++++++++++++++++++++++++--- 2 files changed, 36 insertions(+), 32 deletions(-) diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 6c5865bb5ee8..e6735d2b6ae8 100644 --- a/Documentation/DocBook/gpu.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -615,18 +615,6 @@ char *date; drm_gem_object_init. Storage for private GEM objects must be managed by drivers. - - Drivers that do not need to extend GEM objects with private information - can call the drm_gem_object_alloc function to - allocate and initialize a struct drm_gem_object - instance. The GEM core will call the optional driver - gem_init_object operation after initializing - the GEM object with drm_gem_object_init. - int (*gem_init_object) (struct drm_gem_object *obj); - - - No alloc-and-init function exists for private GEM objects. - GEM Objects Lifetime @@ -649,15 +637,9 @@ char *date; void (*gem_free_object) (struct drm_gem_object *obj); - Drivers are responsible for freeing all GEM object resources, including - the resources created by the GEM core. If an mmap offset has been - created for the object (in which case - drm_gem_object::map_list::map - is not NULL) it must be freed by a call to - drm_gem_free_mmap_offset. The shmfs backing store - must be released by calling drm_gem_object_release - (that function can safely be called if no shmfs backing store has been - created). + Drivers are responsible for freeing all GEM object resources. This includes + the resources created by the GEM core, which need to be released with + drm_gem_object_release. @@ -740,17 +722,10 @@ char *date; DRM identifies the GEM object to be mapped by a fake offset passed through the mmap offset argument. Prior to being mapped, a GEM object must thus be associated with a fake offset. To do so, drivers must call - drm_gem_create_mmap_offset on the object. The - function allocates a fake offset range from a pool and stores the - offset divided by PAGE_SIZE in - obj->map_list.hash.key. Care must be taken not to - call drm_gem_create_mmap_offset if a fake offset - has already been allocated for the object. This can be tested by - obj->map_list.map being non-NULL. + drm_gem_create_mmap_offset on the object. Once allocated, the fake offset value - (obj->map_list.hash.key << PAGE_SHIFT) must be passed to the application in a driver-specific way and can then be used as the mmap offset argument. diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c index 38680380c6b3..c55446a789c7 100644 --- a/drivers/gpu/drm/drm_gem.c +++ b/drivers/gpu/drm/drm_gem.c @@ -244,8 +244,9 @@ drm_gem_object_handle_unreference_unlocked(struct drm_gem_object *obj) * @filp: drm file-private structure to use for the handle look up * @handle: userspace handle to delete * - * Removes the GEM handle from the @filp lookup table and if this is the last - * handle also cleans up linked resources like GEM names. + * Removes the GEM handle from the @filp lookup table which has been added with + * drm_gem_handle_create(). If this is the last handle also cleans up linked + * resources like GEM names. */ int drm_gem_handle_delete(struct drm_file *filp, u32 handle) @@ -314,6 +315,10 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy); * This expects the dev->object_name_lock to be held already and will drop it * before returning. Used to avoid races in establishing new handles when * importing an object from either an flink name or a dma-buf. + * + * Handles must be release again through drm_gem_handle_delete(). This is done + * when userspace closes @file_priv for all attached handles, or through the + * GEM_CLOSE ioctl for individual handles. */ int drm_gem_handle_create_tail(struct drm_file *file_priv, @@ -551,7 +556,17 @@ void drm_gem_put_pages(struct drm_gem_object *obj, struct page **pages, } EXPORT_SYMBOL(drm_gem_put_pages); -/** Returns a reference to the object named by the handle. */ +/** + * drm_gem_object_lookup - look up a GEM object from it's handle + * @dev: DRM device + * @filp: DRM file private date + * @handle: userspace handle + * + * Returns: + * + * A reference to the object named by the handle if such exists on @filp, NULL + * otherwise. + */ struct drm_gem_object * drm_gem_object_lookup(struct drm_device *dev, struct drm_file *filp, u32 handle) @@ -791,6 +806,13 @@ drm_gem_object_free(struct kref *kref) } EXPORT_SYMBOL(drm_gem_object_free); +/** + * drm_gem_vm_open - vma->ops->open implementation for GEM + * @vma: VM area structure + * + * This function implements the #vm_operations_struct open() callback for GEM + * drivers. This must be used together with drm_gem_vm_close(). + */ void drm_gem_vm_open(struct vm_area_struct *vma) { struct drm_gem_object *obj = vma->vm_private_data; @@ -799,6 +821,13 @@ void drm_gem_vm_open(struct vm_area_struct *vma) } EXPORT_SYMBOL(drm_gem_vm_open); +/** + * drm_gem_vm_close - vma->ops->close implementation for GEM + * @vma: VM area structure + * + * This function implements the #vm_operations_struct close() callback for GEM + * drivers. This must be used together with drm_gem_vm_open(). + */ void drm_gem_vm_close(struct vm_area_struct *vma) { struct drm_gem_object *obj = vma->vm_private_data;