From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F3124C433F5 for ; Mon, 18 Apr 2022 15:29:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239204AbiDRPbm (ORCPT ); Mon, 18 Apr 2022 11:31:42 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41700 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S244262AbiDRPbM (ORCPT ); Mon, 18 Apr 2022 11:31:12 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 09E0638A7 for ; Mon, 18 Apr 2022 07:43:16 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 74B7560F55 for ; Mon, 18 Apr 2022 14:43:15 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6235DC385A7; Mon, 18 Apr 2022 14:43:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1650292994; bh=pCzNBiYtmbJhPHrsJO++0NSN3gB8rHy4nNJp5dK5FG8=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=KJXdSyX93GEMJI06EbNkh/Mx/o3MyrubhqW4DG+Zt2+TaUCJmVuML6PM1TO06BJrE MivA7r0x7D5w9wCnMwGCNcMsGQkPY7m1keQ9klUF+OgB4qPI3jOfDC6pCBwuFGTrkR 2dOsLJySE+GWedUqzsQ95oXc3etEnJwdc/dCkS3s2aeFNrVVe/zHon4uBXpXDS0q83 IfHD46LXVgpN6TTmSYpLGm1d02+8FJw2TtxZGUxAL32tPR2b+gc8B6ktJgtfTfUOdd wCLZW55kRRGz9w/mtfl8hP4/lAnBrKqAmB2e+8DzsJknmKBP0TZV/O7EMm6BmsDMzI SeCFP6BLXEFYA== Date: Mon, 18 Apr 2022 17:43:05 +0300 From: Mike Rapoport To: "Fabio M. De Francesco" Cc: Ira Weiny , Andrew Morton , Catalin Marinas , "Matthew Wilcox (Oracle)" , Will Deacon , Peter Collingbourne , Vlastimil Babka , Sebastian Andrzej Siewior , linux-kernel@vger.kernel.org, outreachy@lists.linux.dev Subject: Re: [PATCH] mm/highmem: Fix kernel-doc warnings in highmem*.h Message-ID: References: <20220418075304.20259-1-fmdefrancesco@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20220418075304.20259-1-fmdefrancesco@gmail.com> Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi, On Mon, Apr 18, 2022 at 09:53:04AM +0200, Fabio M. De Francesco wrote: > `scripts/kernel-doc -none include/linux/highmem*` reports the following > warnings: > > include/linux/highmem.h:160: warning: expecting prototype for kunmap_atomic(). Prototype was for nr_free_highpages() instead > include/linux/highmem-internal.h:256: warning: Function parameter or member '__addr' not described in 'kunmap_atomic' > include/linux/highmem-internal.h:256: warning: Excess function parameter 'addr' description in 'kunmap_atomic' > > Fix these warnings by (1) move the kernel-doc comments from highmem.h to > highmem-internal.h (which is the file were the kunmap_atomic() macro is > actually defined), merge it with the comment which already was in ^ (2) ? > highmem-internal.h, and (3) replace "@addr" with "@__addr". There is also replacement of "addr" with "page", so I'd phrase (3) as "use correct parameter names" > Signed-off-by: Fabio M. De Francesco Other than that Acked-by: Mike Rapoport > --- > include/linux/highmem-internal.h | 14 +++++++++++--- > include/linux/highmem.h | 13 +------------ > 2 files changed, 12 insertions(+), 15 deletions(-) > > diff --git a/include/linux/highmem-internal.h b/include/linux/highmem-internal.h > index a77be5630209..7307de391288 100644 > --- a/include/linux/highmem-internal.h > +++ b/include/linux/highmem-internal.h > @@ -236,9 +236,17 @@ static inline unsigned long totalhigh_pages(void) { return 0UL; } > > #endif /* CONFIG_HIGHMEM */ > > -/* > - * Prevent people trying to call kunmap_atomic() as if it were kunmap() > - * kunmap_atomic() should get the return value of kmap_atomic, not the page. > +/** > + * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() > + * @__addr: Virtual address to be unmapped > + * > + * Counterpart to kmap_atomic(). > + * > + * Effectively a wrapper around kunmap_local() which additionally undoes > + * the side effects of kmap_atomic(), i.e. reenabling pagefaults and > + * preemption. Prevent people trying to call kunmap_atomic() as if it > + * were kunmap() because kunmap_atomic() should get the return value of > + * kmap_atomic(), not its argument which is a pointer to struct page. > */ > #define kunmap_atomic(__addr) \ > do { \ > diff --git a/include/linux/highmem.h b/include/linux/highmem.h > index 39bb9b47fa9c..0a7a89721e5d 100644 > --- a/include/linux/highmem.h > +++ b/include/linux/highmem.h > @@ -37,7 +37,7 @@ static inline void *kmap(struct page *page); > > /** > * kunmap - Unmap the virtual address mapped by kmap() > - * @addr: Virtual address to be unmapped > + * @page: Virtual address to be unmapped > * > * Counterpart to kmap(). A NOOP for CONFIG_HIGHMEM=n and for mappings of > * pages in the low memory area. > @@ -145,17 +145,6 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset); > */ > static inline void *kmap_atomic(struct page *page); > > -/** > - * kunmap_atomic - Unmap the virtual address mapped by kmap_atomic() > - * @addr: Virtual address to be unmapped > - * > - * Counterpart to kmap_atomic(). > - * > - * Effectively a wrapper around kunmap_local() which additionally undoes > - * the side effects of kmap_atomic(), i.e. reenabling pagefaults and > - * preemption. > - */ > - > /* Highmem related interfaces for management code */ > static inline unsigned int nr_free_highpages(void); > static inline unsigned long totalhigh_pages(void); > -- > 2.34.1 > > -- Sincerely yours, Mike.