From patchwork Sun Dec 31 05:48:56 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 184090 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:6f82:b0:100:9c79:88ff with SMTP id tb2csp3379252dyb; Sat, 30 Dec 2023 21:49:18 -0800 (PST) X-Google-Smtp-Source: AGHT+IFCelAB3EDPTxiqjvpNAmcXvocmMF3rKQsKiECpPIHK028wirmIk5dU80krf5USYRv8qMYj X-Received: by 2002:a05:6a20:800a:b0:18f:97c:8267 with SMTP id e10-20020a056a20800a00b0018f097c8267mr5906854pza.113.1704001758551; Sat, 30 Dec 2023 21:49:18 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704001758; cv=none; d=google.com; s=arc-20160816; b=EfSESW9YQrzMwEwAeJwQi9Shnkzqq8JqrpQ9l6Qw7Im9q+HvNZ9knakDO7eUtf7/oR a2tuEjgVwOyLweiCi8dLSVMlHkaV4tirYivb6O1XFVvxz9BS5H9JmmqRaoeriTLKkawp Y/8FvdspYx3tOzO/q8xcZk9KjWcz5MH8SKGSCUy+JnBrOGDlRQ8CjWD2op/cNKzBDm0l 14SNs6MdRdMruMei9d2wglErQqytj5P+i0SJoEk6u5lcqLNisqq3TudrfpKdPmK2CbRd /0o34vBQjgR+3/WmW4nsEaNk0yGlH7DBL6rbcnLTUcHgE9hRDxMmua3GU0nHmezyUGPW 8meg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:message-id:date:subject:cc:to :from:dkim-signature; bh=BESTCzzD+5VKhuQ+KvwSqvUyr0NIxH77E9a/qlyXlEo=; fh=JqO7X/1QV8nQD/x03uORIImr/qr5Jiq1EyQnFpLZ5bQ=; b=zvAdP7SxGrLnUuuP+kgeN0PSTTmFzVvPfTHbNtwcxrC5Mt1v6BErn3WyG4ZyIFF54X UsqA2EX+CSM6DwnRaYdOx5cVRFM+ubdRzYkggUCd0ai6/nAUTZ94CFJ2JMSebQ+/fH+v aBbYpzUDPwn8mU7F2cWfCUgt2oFsdifn19DkiFGxm1sMAxCNZGQDLFyHxr/YHQ00CJsq gUs9JcwpHZMJHFGMOvR5H7h89JUW7FWXqZjIDTzxC6vmxZtWyyIQcLMQkqGiWM8mOWzu /pPV4omOPw7TCGmH9efER9wgPh9eu99a03Ahc2LDzDLJOUxiz9Mchg4Z9xMmpaRQ4hzl 3OjA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=hArNe9pU; spf=pass (google.com: domain of linux-kernel+bounces-13639-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-13639-ouuuleilei=gmail.com@vger.kernel.org" Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [2604:1380:40f1:3f00::1]) by mx.google.com with ESMTPS id t12-20020a170902e84c00b001d4aeb50b18si1069371plg.514.2023.12.30.21.49.18 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 30 Dec 2023 21:49:18 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-13639-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=hArNe9pU; spf=pass (google.com: domain of linux-kernel+bounces-13639-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-13639-ouuuleilei=gmail.com@vger.kernel.org" Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sy.mirrors.kernel.org (Postfix) with ESMTPS id 68D13B216DA for ; Sun, 31 Dec 2023 05:49:17 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 9E562258F; Sun, 31 Dec 2023 05:49:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="hArNe9pU" X-Original-To: linux-kernel@vger.kernel.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id CC42617C7 for ; Sun, 31 Dec 2023 05:48:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:Message-ID:Date:Subject:Cc:To:From:Sender:Reply-To:Content-Type: Content-ID:Content-Description:In-Reply-To:References; bh=BESTCzzD+5VKhuQ+KvwSqvUyr0NIxH77E9a/qlyXlEo=; b=hArNe9pULz6W0hnjtIE/d7bFFx ioHpEvdg/KC7xYU8BkMU/dk5kG7vxIpxzi4oVnKOVBuIMZwcM9Sqv+tAcMspLTfttTYG7KchoQ3rq JTc7EgBKfira7vkW0ZvpXnwuMPJ0+OUgg6mM8nSMctUmMfzDdNxtAv74794zNNP107oimt+7OdhSq gKeZskjyoj/+exn+cGKcs42FvOPvIXkBA0ikW2kpd1Ol+SXB5Vg+DZj29OPYSBn9CR+jtF4u4sgR7 dwQStepemYtJ+/8MKRxGgFcbBaYNWF0ayep6O10qh4vGhb+4ufKB6WAnO+2+bRT/SATpBv7LH2yz2 c26k6K4g==; Received: from [50.53.46.231] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1rJogy-0041ad-2u; Sun, 31 Dec 2023 05:48:56 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , David Airlie , Daniel Vetter , dri-devel@lists.freedesktop.org, Jonathan Corbet , Vegard Nossum Subject: [PATCH] drm/gpuvm: fix all kernel-doc warnings in include/drm/drm_gpuvm.h Date: Sat, 30 Dec 2023 21:48:56 -0800 Message-ID: <20231231054856.31786-1-rdunlap@infradead.org> X-Mailer: git-send-email 2.43.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1786775347806294814 X-GMAIL-MSGID: 1786775347806294814 Update kernel-doc comments in to correct all kernel-doc warnings: drm_gpuvm.h:148: warning: Excess struct member 'addr' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'offset' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'obj' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'entry' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member '__subtree_last' description in 'drm_gpuva' drm_gpuvm.h:192: warning: No description found for return value of 'drm_gpuva_invalidated' drm_gpuvm.h:331: warning: Excess struct member 'tree' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'local_list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'lock' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'local_list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'lock' description in 'drm_gpuvm' drm_gpuvm.h:352: warning: No description found for return value of 'drm_gpuvm_get' drm_gpuvm.h:545: warning: Excess struct member 'fn' description in 'drm_gpuvm_exec' drm_gpuvm.h:545: warning: Excess struct member 'priv' description in 'drm_gpuvm_exec' drm_gpuvm.h:597: warning: missing initial short description on line: * drm_gpuvm_exec_resv_add_fence() drm_gpuvm.h:616: warning: missing initial short description on line: * drm_gpuvm_exec_validate() drm_gpuvm.h:623: warning: No description found for return value of 'drm_gpuvm_exec_validate' drm_gpuvm.h:698: warning: Excess struct member 'gpuva' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'entry' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'gem' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'evict' description in 'drm_gpuvm_bo' drm_gpuvm.h:726: warning: No description found for return value of 'drm_gpuvm_bo_get' drm_gpuvm.h:738: warning: missing initial short description on line: * drm_gpuvm_bo_gem_evict() drm_gpuvm.h:740: warning: missing initial short description on line: * drm_gpuvm_bo_gem_evict() drm_gpuvm.h:698: warning: Excess struct member 'evict' description in 'drm_gpuvm_bo' drm_gpuvm.h:844: warning: Excess struct member 'addr' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'range' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'offset' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'obj' description in 'drm_gpuva_op_map' Signed-off-by: Randy Dunlap Cc: Maarten Lankhorst Cc: Maxime Ripard Cc: Thomas Zimmermann Cc: David Airlie Cc: Daniel Vetter Cc: dri-devel@lists.freedesktop.org Cc: Jonathan Corbet Cc: Vegard Nossum --- include/drm/drm_gpuvm.h | 80 +++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 35 deletions(-) diff -- a/include/drm/drm_gpuvm.h b/include/drm/drm_gpuvm.h --- a/include/drm/drm_gpuvm.h +++ b/include/drm/drm_gpuvm.h @@ -92,7 +92,7 @@ struct drm_gpuva { */ struct { /** - * @addr: the start address + * @va.addr: the start address */ u64 addr; @@ -107,17 +107,17 @@ struct drm_gpuva { */ struct { /** - * @offset: the offset within the &drm_gem_object + * @gem.offset: the offset within the &drm_gem_object */ u64 offset; /** - * @obj: the mapped &drm_gem_object + * @gem.obj: the mapped &drm_gem_object */ struct drm_gem_object *obj; /** - * @entry: the &list_head to attach this object to a &drm_gpuvm_bo + * @gem.entry: the &list_head to attach this object to a &drm_gpuvm_bo */ struct list_head entry; } gem; @@ -127,12 +127,12 @@ struct drm_gpuva { */ struct { /** - * @rb: the rb-tree node + * @rb.node: the rb-tree node */ struct rb_node node; /** - * @entry: The &list_head to additionally connect &drm_gpuvas + * @rb.entry: The &list_head to additionally connect &drm_gpuvas * in the same order they appear in the interval tree. This is * useful to keep iterating &drm_gpuvas from a start node found * through the rb-tree while doing modifications on the rb-tree @@ -141,7 +141,7 @@ struct drm_gpuva { struct list_head entry; /** - * @__subtree_last: needed by the interval tree, holding last-in-subtree + * @rb.__subtree_last: needed by the interval tree, holding last-in-subtree */ u64 __subtree_last; } rb; @@ -187,6 +187,8 @@ static inline void drm_gpuva_invalidate( * drm_gpuva_invalidated() - indicates whether the backing BO of this &drm_gpuva * is invalidated * @va: the &drm_gpuva to check + * + * Returns: %true if the GPU VA is invalidated, %false otherwise */ static inline bool drm_gpuva_invalidated(struct drm_gpuva *va) { @@ -252,12 +254,12 @@ struct drm_gpuvm { */ struct { /** - * @tree: the rb-tree to track GPU VA mappings + * @rb.tree: the rb-tree to track GPU VA mappings */ struct rb_root_cached tree; /** - * @list: the &list_head to track GPU VA mappings + * @rb.list: the &list_head to track GPU VA mappings */ struct list_head list; } rb; @@ -290,19 +292,19 @@ struct drm_gpuvm { */ struct { /** - * @list: &list_head storing &drm_gpuvm_bos serving as + * @extobj.list: &list_head storing &drm_gpuvm_bos serving as * external object */ struct list_head list; /** - * @local_list: pointer to the local list temporarily storing - * entries from the external object list + * @extobj.local_list: pointer to the local list temporarily + * storing entries from the external object list */ struct list_head *local_list; /** - * @lock: spinlock to protect the extobj list + * @extobj.lock: spinlock to protect the extobj list */ spinlock_t lock; } extobj; @@ -312,19 +314,19 @@ struct drm_gpuvm { */ struct { /** - * @list: &list_head storing &drm_gpuvm_bos currently being - * evicted + * @evict.list: &list_head storing &drm_gpuvm_bos currently + * being evicted */ struct list_head list; /** - * @local_list: pointer to the local list temporarily storing - * entries from the evicted object list + * @evict.local_list: pointer to the local list temporarily + * storing entries from the evicted object list */ struct list_head *local_list; /** - * @lock: spinlock to protect the evict list + * @evict.lock: spinlock to protect the evict list */ spinlock_t lock; } evict; @@ -344,6 +346,8 @@ void drm_gpuvm_init(struct drm_gpuvm *gp * * This function acquires an additional reference to @gpuvm. It is illegal to * call this without already holding a reference. No locks required. + * + * Returns: the &struct drm_gpuvm pointer */ static inline struct drm_gpuvm * drm_gpuvm_get(struct drm_gpuvm *gpuvm) @@ -533,12 +537,13 @@ struct drm_gpuvm_exec { */ struct { /** - * @fn: The driver callback to lock additional &drm_gem_objects. + * @extra.fn: The driver callback to lock additional + * &drm_gem_objects. */ int (*fn)(struct drm_gpuvm_exec *vm_exec); /** - * @priv: driver private data for the @fn callback + * @extra.priv: driver private data for the @fn callback */ void *priv; } extra; @@ -589,7 +594,7 @@ void drm_gpuvm_resv_add_fence(struct drm enum dma_resv_usage extobj_usage); /** - * drm_gpuvm_exec_resv_add_fence() + * drm_gpuvm_exec_resv_add_fence() - add fence to private and all extobj * @vm_exec: the &drm_gpuvm_exec wrapper * @fence: fence to add * @private_usage: private dma-resv usage @@ -608,10 +613,12 @@ drm_gpuvm_exec_resv_add_fence(struct drm } /** - * drm_gpuvm_exec_validate() + * drm_gpuvm_exec_validate() - validate all BOs marked as evicted * @vm_exec: the &drm_gpuvm_exec wrapper * * See drm_gpuvm_validate(). + * + * Returns: 0 on success, negative error code on failure. */ static inline int drm_gpuvm_exec_validate(struct drm_gpuvm_exec *vm_exec) @@ -664,7 +671,7 @@ struct drm_gpuvm_bo { */ struct { /** - * @gpuva: The list of linked &drm_gpuvas. + * @list.gpuva: The list of linked &drm_gpuvas. * * It is safe to access entries from this list as long as the * GEM's gpuva lock is held. See also struct drm_gem_object. @@ -672,25 +679,25 @@ struct drm_gpuvm_bo { struct list_head gpuva; /** - * @entry: Structure containing all &list_heads serving as + * @list.entry: Structure containing all &list_heads serving as * entry. */ struct { /** - * @gem: List entry to attach to the &drm_gem_objects - * gpuva list. + * @list.entry.gem: List entry to attach to the + * &drm_gem_objects gpuva list. */ struct list_head gem; /** - * @evict: List entry to attach to the &drm_gpuvms - * extobj list. + * @list.entry.evict: List entry to attach to the + * &drm_gpuvms extobj list. */ struct list_head extobj; /** - * @evict: List entry to attach to the &drm_gpuvms evict - * list. + * @list.entry.evict: List entry to attach to the + * &drm_gpuvms evict list. */ struct list_head evict; } entry; @@ -713,6 +720,8 @@ drm_gpuvm_bo_obtain_prealloc(struct drm_ * * This function acquires an additional reference to @vm_bo. It is illegal to * call this without already holding a reference. No locks required. + * + * Returns: the &struct vm_bo pointer */ static inline struct drm_gpuvm_bo * drm_gpuvm_bo_get(struct drm_gpuvm_bo *vm_bo) @@ -730,7 +739,8 @@ drm_gpuvm_bo_find(struct drm_gpuvm *gpuv void drm_gpuvm_bo_evict(struct drm_gpuvm_bo *vm_bo, bool evict); /** - * drm_gpuvm_bo_gem_evict() + * drm_gpuvm_bo_gem_evict() - add/remove all &drm_gpuvm_bo's in the list + * to/from the &drm_gpuvms evicted list * @obj: the &drm_gem_object * @evict: indicates whether @obj is evicted * @@ -817,12 +827,12 @@ struct drm_gpuva_op_map { */ struct { /** - * @addr: the base address of the new mapping + * @va.addr: the base address of the new mapping */ u64 addr; /** - * @range: the range of the new mapping + * @va.range: the range of the new mapping */ u64 range; } va; @@ -832,12 +842,12 @@ struct drm_gpuva_op_map { */ struct { /** - * @offset: the offset within the &drm_gem_object + * @gem.offset: the offset within the &drm_gem_object */ u64 offset; /** - * @obj: the &drm_gem_object to map + * @gem.obj: the &drm_gem_object to map */ struct drm_gem_object *obj; } gem;