From nobody Thu Apr 16 07:10:00 2026 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 6AB74DDC5 for ; Mon, 2 Mar 2026 00:52:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772412747; cv=none; b=f9RdOMvWWTsGnUhBKD1skVysM8SAQgli0pJOs1RpgXz6cX016wBfNe6NVH6/eWReokY5C7ZImTzpJxMc40SyWz4ABgoxRNrz1N6k1Ixb3ey8EGUXK9ND+lAEOxFzdPuriNWvAKpdMUMtsZ4oljx3XB2MVILP6WWuL3CEh6AkYY4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772412747; c=relaxed/simple; bh=fCiLFz9fDowg1Q0GcyjQNksopAVJ6l4zuBeETlIBmo0=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=IzcN+jTgImSzmuftvD0dFTHRcibmWWLnWV+FYZBKoSrKyJHBKTE0RLWJmLgiWRKzBwuzPCxyuPPMBX8jZe1rSGz5M9RqxMBfXNFDIRP3ERD2bwEHFLKgKDUhLs3JUKhRGpNk4cDRgTqTf5kgIcBLtbYfuoeNDL1o6FCmUUqNNpY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=EIZnaf1L; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="EIZnaf1L" 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=7saKVzOxoyQVzyoMxc8/Swddr+JmA7XALf/AIy5p+cY=; b=EIZnaf1LogeAFGwueIIyStDp40 dZvB6cVWaM1ypJEa1iEVroUhyMlGvdQFCu0plYLrJlfsrfe/x44Lsv49F2TTa82JZ+AX06vLXmjJ1 NrFxd7gOZPH3gG1ner+rVF+wnB4rIIEIHXoZEyBuwWWaqjiUw7XraUKw3p+QuLL3lfMXuOPTZeWCe MuS7LohQDtELwvl1L7315gP9HLYfAyvgnJsz9yx1sApxiYJMVlmP84kkpvOnEArS1lOIG7IBhvjvR kcNYmzxBuKX70JCX8WFaWXevM9aJscMtD69upRzt97V+n+JmJxXSCb6fMh8hnKZ2VnTsvhtuS8uUJ E+WgBkUg==; Received: from [50.53.43.113] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1vwrWK-0000000C28F-1yWy; Mon, 02 Mar 2026 00:52:24 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jason Gunthorpe , Andrew Morton , linux-mm@kvack.org Subject: [PATCH] mm/mmu_notifier: clean up mmu_notifier.h kernel-doc Date: Sun, 1 Mar 2026 16:52:22 -0800 Message-ID: <20260302005222.3470783-1-rdunlap@infradead.org> X-Mailer: git-send-email 2.53.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Eliminate kernel-doc warnings in mmu_notifier.h: - add a missing struct short description - use the correct format for function parameters - add missing function return comment sections Warning: include/linux/mmu_notifier.h:236 missing initial short description on line: * struct mmu_interval_notifier_ops Warning: include/linux/mmu_notifier.h:325 function parameter 'interval_sub' not described in 'mmu_interval_set_seq' Warning: include/linux/mmu_notifier.h:325 function parameter 'cur_seq' not described in 'mmu_interval_set_seq' Warning: include/linux/mmu_notifier.h:346 function parameter 'interval_sub' not described in 'mmu_interval_read_retry' Warning: include/linux/mmu_notifier.h:346 function parameter 'seq' not described in 'mmu_interval_read_retry' Warning: include/linux/mmu_notifier.h:346 No description found for return value of 'mmu_interval_read_retry' Warning: include/linux/mmu_notifier.h:370 function parameter 'interval_sub' not described in 'mmu_interval_check_retry' Warning: include/linux/mmu_notifier.h:370 function parameter 'seq' not described in 'mmu_interval_check_retry' Warning: include/linux/mmu_notifier.h:370 No description found for return value of 'mmu_interval_check_retry' Signed-off-by: Randy Dunlap Reviewed-by: Jason Gunthorpe --- Cc: Jason Gunthorpe Cc: Andrew Morton Cc: linux-mm@kvack.org include/linux/mmu_notifier.h | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) --- linux-next-20260227.orig/include/linux/mmu_notifier.h +++ linux-next-20260227/include/linux/mmu_notifier.h @@ -234,7 +234,7 @@ struct mmu_notifier { }; =20 /** - * struct mmu_interval_notifier_ops + * struct mmu_interval_notifier_ops - callback for range notification * @invalidate: Upon return the caller must stop using any SPTEs within th= is * range. This function can sleep. Return false only if sleep= ing * was required but mmu_notifier_range_blockable(range) is fa= lse. @@ -309,8 +309,8 @@ void mmu_interval_notifier_remove(struct =20 /** * mmu_interval_set_seq - Save the invalidation sequence - * @interval_sub - The subscription passed to invalidate - * @cur_seq - The cur_seq passed to the invalidate() callback + * @interval_sub: The subscription passed to invalidate + * @cur_seq: The cur_seq passed to the invalidate() callback * * This must be called unconditionally from the invalidate callback of a * struct mmu_interval_notifier_ops under the same lock that is used to ca= ll @@ -329,8 +329,8 @@ mmu_interval_set_seq(struct mmu_interval =20 /** * mmu_interval_read_retry - End a read side critical section against a VA= range - * interval_sub: The subscription - * seq: The return of the paired mmu_interval_read_begin() + * @interval_sub: The subscription + * @seq: The return of the paired mmu_interval_read_begin() * * This MUST be called under a user provided lock that is also held * unconditionally by op->invalidate() when it calls mmu_interval_set_seq(= ). @@ -338,7 +338,7 @@ mmu_interval_set_seq(struct mmu_interval * Each call should be paired with a single mmu_interval_read_begin() and * should be used to conclude the read side. * - * Returns true if an invalidation collided with this critical section, and + * Returns: true if an invalidation collided with this critical section, a= nd * the caller should retry. */ static inline bool @@ -350,20 +350,21 @@ mmu_interval_read_retry(struct mmu_inter =20 /** * mmu_interval_check_retry - Test if a collision has occurred - * interval_sub: The subscription - * seq: The return of the matching mmu_interval_read_begin() + * @interval_sub: The subscription + * @seq: The return of the matching mmu_interval_read_begin() * * This can be used in the critical section between mmu_interval_read_begi= n() - * and mmu_interval_read_retry(). A return of true indicates an invalidat= ion - * has collided with this critical region and a future - * mmu_interval_read_retry() will return true. - * - * False is not reliable and only suggests a collision may not have - * occurred. It can be called many times and does not have to hold the user - * provided lock. + * and mmu_interval_read_retry(). * * This call can be used as part of loops and other expensive operations to * expedite a retry. + * It can be called many times and does not have to hold the user + * provided lock. + * + * Returns: true indicates an invalidation has collided with this critical + * region and a future mmu_interval_read_retry() will return true. + * False is not reliable and only suggests a collision may not have + * occurred. */ static inline bool mmu_interval_check_retry(struct mmu_interval_notifier *interval_sub,