From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-ej1-f52.google.com (mail-ej1-f52.google.com [209.85.218.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 23DC47F5 for ; Wed, 27 Apr 2022 18:38:30 +0000 (UTC) Received: by mail-ej1-f52.google.com with SMTP id gh6so5220577ejb.0 for ; Wed, 27 Apr 2022 11:38:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3A9Xsphph+SQIianXjBh4+4o7zyb9BLunLh+E/0CQio=; b=UnfU+HKtW2D06NU0bNOq17sb224h2OOputwJe94u41Qt8hwta0lHaQFIp972VNxMxw NidlrzU1EDNDzfMvPXwIjMrmvr1NjR37cOhY1nYV+roOMxaNJKralBkSBGKZ/BN5Th8s N9lRPYTPjGbr0cSTjbxEspuArLVLDdoBPgK6+upGAizAiELcdp5a9hMp/Xoahvusgq57 Th2ISXRFFfvep7ONNLZ0oteYokL2E120n27AHTizXeVhQ6Z8Bx7kArRZNl0nJnyk3Zz+ 9wm2qfNSgd9FOpItl1vN8l1QYWQbKpnNcH79auchDN29l0o91cDPqLo/49TJ8Kt/t9PO 5Vvg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=3A9Xsphph+SQIianXjBh4+4o7zyb9BLunLh+E/0CQio=; b=6Fe4BmAywvBW8ZZJlEtqYnWUuFQ+53/u/VXrsCKLvArXbtqBl1HRjAu4cCvfUwxmZQ Rtl220TPCERFdytU9FA3T1r0ff+pc9w7LBWT+hLeDOjN+NThUSnrs+848ADHk3tQk/o8 7fTG5NwbOvPacwyp9/1FmrA/un7Wy0rKp7pO2myvtKhiUQWCi4JZ7fsjzTt1os58iAPU 9U8TK11I6lm9iMp6lYNjkM3/g+zSxjBJo3R8fWvfdBc+3pgdblMW4auNKIs/2bh/W+gh yocc465tHTE5m7m1dWiELyHbo+QsSTh2Lnj+Gtto5wuZhOvhdeCZTCCw6YYCPzy7WdUN NZFw== X-Gm-Message-State: AOAM532NR6TjgmqTfIR6D8ensDpx4yJGmTTNn88V/SaSdF6kJKFeyCeh RlQoA4D0TyyaYfj7r4/dEbrku9myz6A= X-Google-Smtp-Source: ABdhPJwbRHA28mPeqny4TiNCbUmpYR75vpZN6jbYw41zpIX7FDWDTPi4S99nZfjEdPb0JJjaOjNyZw== X-Received: by 2002:a17:907:da0:b0:6df:d4a4:9d0f with SMTP id go32-20020a1709070da000b006dfd4a49d0fmr29043562ejc.407.1651084708394; Wed, 27 Apr 2022 11:38:28 -0700 (PDT) Received: from localhost.localdomain (host-79-50-86-254.retail.telecomitalia.it. [79.50.86.254]) by smtp.gmail.com with ESMTPSA id ig8-20020a1709072e0800b006f38f2e9ebesm4691667ejc.64.2022.04.27.11.38.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Apr 2022 11:38:27 -0700 (PDT) From: "Fabio M. De Francesco" To: Ira Weiny , Andrew Morton , Catalin Marinas , "Matthew Wilcox (Oracle)" , Will Deacon , Peter Collingbourne , Vlastimil Babka , Sebastian Andrzej Siewior , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, outreachy@lists.linux.dev Cc: "Fabio M. De Francesco" , Mike Rapoport Subject: [PATCH v3 1/4] mm/highmem: Fix kernel-doc warnings in highmem*.h Date: Wed, 27 Apr 2022 20:38:18 +0200 Message-Id: <20220427183821.1979-2-fmdefrancesco@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220427183821.1979-1-fmdefrancesco@gmail.com> References: <20220427183821.1979-1-fmdefrancesco@gmail.com> Precedence: bulk X-Mailing-List: outreachy@lists.linux.dev List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit `scripts/kernel-doc -v -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.h:204: warning: No description found for return value of 'alloc_zeroed_user_highpage_movable' 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) moving the kernel-doc comments from highmem.h to highmem-internal.h (which is the file were the kunmap_atomic() macro is actually defined), (2) extending and merging it with the comment which was already in highmem-internal.h, (3) using correct parameter names, (4) adding description of return value of alloc_zeroed_user_highpage_movable(), (5) correcting some technical inaccuracies in comments, and (5) adding a deprecation notice in kunmap_atomic() for consistency with kmap_atomic(). Cc: Matthew Wilcox Cc: Sebastian Andrzej Siewior Acked-by: Mike Rapoport Reviewed-by: Ira Weiny Signed-off-by: Fabio M. De Francesco --- include/linux/highmem-internal.h | 15 ++++++++++++--- include/linux/highmem.h | 20 ++++++-------------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/include/linux/highmem-internal.h b/include/linux/highmem-internal.h index a77be5630209..9968a1282317 100644 --- a/include/linux/highmem-internal.h +++ b/include/linux/highmem-internal.h @@ -236,9 +236,18 @@ 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() - deprecated! + * @__addr: Virtual address to be unmapped + * + * Unmaps an address previously mapped by kmap_atomic() and re-enables + * pagefaults, migration, preemption (the latter was disabled only for + * !PREEMP_RT configurations). Mappings should be unmapped in the reverse + * order that they were mapped. See kmap_local_page() for details. + * @__addr can be any address within the mapped page, so there is no need + * to subtract any offset that has been added. In contrast to kunmap(), + * this function takes the address returned from kmap_atomic(), not the + * page passed to it. The compiler will warn you if you pass the page. */ #define kunmap_atomic(__addr) \ do { \ diff --git a/include/linux/highmem.h b/include/linux/highmem.h index 39bb9b47fa9c..3623319a659d 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: Pointer to the page which was mapped by kmap() * * Counterpart to kmap(). A NOOP for CONFIG_HIGHMEM=n and for mappings of * pages in the low memory area. @@ -138,24 +138,14 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset); * * Returns: The virtual address of the mapping * - * Effectively a wrapper around kmap_local_page() which disables pagefaults - * and preemption. + * In fact a wrapper around kmap_local_page() which disables pagefaults, + * migration, preemption (the latter disabled only for !PREEMP_RT + * configurations). * * Do not use in new code. Use kmap_local_page() instead. */ 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); @@ -191,6 +181,8 @@ static inline void clear_user_highpage(struct page *page, unsigned long vaddr) * @vma: The VMA the page is to be allocated for * @vaddr: The virtual address the page will be inserted into * + * Returns: The allocated and zeroed HIGHMEM page + * * This function will allocate a page for a VMA that the caller knows will * be able to migrate in the future using move_pages() or reclaimed * -- 2.34.1